64 Display Window end Treed 


64 Display Window and Trace 


The C structures, variables, and routines detailed in this section control the type and location 
of certain displays on the INTERVIEW. These displays can be grouped into three categories. 

The first display area is the prompt line, the second line on all Run-mode screens. 

The second type of display utilizes the Display Window, available as a selection on the Display 
Setup portion of the Line Setup menu, or conditionally accessible via softkey during Run 
mode, To write to the Display Window, use the pos_cursor (or restore _cursor) and displayc, 
display/, or displays routines. When using Display Window, you may position the cursor 
before output is generated on the screen. 

The third type of display utilizes one or a combination of the eight available trace buffers. 
Trace screens are conditionally accessible via softkey during Run mode. Seven user-traces 
appear as choices under the User Trace selection on the Display Setup menu. The remaining 
trace is Program Trace, also an option on Display Setup. Program Trace enables you to track 
any or all layers, one or all tests, and movement between states. To write to any of the eight 
trace-screens, use the tracec, trace/, and traces routines. 


NOTE: You may not use the posjeursor routine to position the 
cursor on any trace screen. New lines (or blank lines) may be 
generated via the "\n” specifier. 


Attributes— color, underlining, and font, for example— may be assigned to characters in the 
Display Window and all of the Trace buffers. 


NOTE: Color attributes are applied to the RGB output signal, 
not to the plasma screen. 


64.1 Current Display Mode 

A group of variables keeps track of softkey movement from one display screen to 
another (see Table 64-1). When you move from the Display Window to the Program 
Trace screen, for example, the /ast-event variable display _screen_changed indicates 
the change of display. The coded value for Display Window now is stored in 
prevjdisplay^screen, and the value for Program Trace can be found in 
crnt_display_screen . 
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These variables also distinguish between Run mode and Freeze mode. This 
distinction is important since some keys on the keyboard are mode-dependent. In 
Freeze mode, for instance, cursor keys automatically become operational for scrolling 
through the buffer. The programmer will want to avoid using these keys as 
user-input when crnt_display_screen indicates that the unit is in Freeze mode. 

Table 64-1 

Current Display Variables 


Type 


Variable Value (hex/decimal) Meaning 


extern fast_event display _screen_changed True when Run-mode 

display-screen Is changed, or 
when Run/Freeze mode Is 
changed. Value In 
crnt_dlsplayjscreen Is stored In 
prav_dlsplay_screen , and 
crnt_dlsplay-screen Is updated. 
Line Setup configured for 
emulate or monitor mode. 

extern unsigned short crnt_dlsplay_screen Contains current display screen 

(low byte) and Indicates whether 
unit Is In Run mode or Freeze 
mode (high byte). Line Setup 
configured for emulate or 
monitor mode. 


display-screen 


0 

no display 

1 

single-line data 

2 

dual-line data 

3 

slngle-llne data with leads 

4 

dual-line data with leads 

11/17 

tabular statistics 

12/18 

graphic statistics 

21/33 

Display Window 

31/49 

Program Trace 

41/85 

Layer 1 Protocol Trace 

42/66 

Layer 2 Protocol Trace 

43/67 

Layer 3 Protocol Trace 

44/68 

Layer 4 Protocol Trace 

45/69 

Layer 5 Protocol Trace 

46/70 

Layer 6 Protocol Trace 

47/71 

Layer 7 Protocol Trace 

51/81 

User Trace 1 

52/82 

User Trace 2 

53/63 

User Trace 3 

54/84 

User Trace 4 

55/85 

User Trace 5 

56/86 

User Trace 6 

57/87 

User Trace 7 

61/97 

TIM package standard sta 

62/98 

TIM package aux 
Run/Freeze mode (bit 9) 

100/256 

Freeze mode 

0 

Run mode 
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Table 64-1 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

extern unsigned short 

prevjilsplay_screen 


Contains previous display screen 
(low byte) and Indicates whether 
unit was In Run mode or Freeze 




mode (high byte). Line Setup 
configured for emulate or 
monitor mode. 




dlsplay-soreen 



0 

no display 



1 

slngle-llne data 



2 

dual-line data 



3 

slngle-llne data with leads 



4 

dual-line data with leads 



11/17 

tabular statistics 



12/18 

graphic statistics 



21/33 

Display Window 



31/49 

Program Trace 



41/65 

Layer 1 Protocol Trace 



42/66 

Layer 2 Protocol Trace 



43/67 

Layer 3 Protoool Trace 



44/68 

Layer 4 Protocol Trace 



45/69 

Layer 5 Protocol Trace 



46/70 

Layer 6 Protocol Trace 



47/71 

Layer 7 Protocol Trace 



51/81 

User Trace 1 



52/82 

User Trace 2 



53/83 

User Trace 3 



54/84 

User Trace 4 



55/85 

User Trace 5 



56/86 

User Trace 6 



57/87 

User Trace 7 



61/97 

TIM package standard stats 



62/98 

TIM package aux 
RunIFreeze mode (bit 9) 



100/256 

Freeze mode 



0 

Run mode 


64.2 Prompt Line 

Access to the prompt line is always available via the display _prompt routine, or its 
softkey equivalent, the PROMPT action. Attributes may not be assigned to a prompt 
created via either of these methods. (To create a prompt with attributes, use the 
pos_cursor and display f routines.) Prompts appear on whatever screen is active at 
the time the prompt is written, including trace screens. With one exception, 
movement to another display erases the prompt. The only screen which retains the 
most recent prompt is the Display Window. 

You may also position the cursor to the prompt line in the Display Window via the 
pos_cursor routine. The initial position of the cursor in the Display Window is at the 
beginning of the prompt line— row zero, column zero. Anything written to this cursor 
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position in the Display Window will appear as a prompt on any one of the other 
display screens (assuming one of them is active at the time the message is written). 
Position the cursor below the prompt line for messages intended for the Display 
Window only. 

Trace buffers retain no record of prompts. When you write to a trace screen, the 
initial position of the cursor is the line immediately below the prompt line— row one. 
Since you may not position the cursor in trace buffers, all messages written to trace 
buffers are appended at the end of the buffer. You may never access the prompt 
line via tracef (or iracec or traces) routines. 

64.3 Display Window 

The Display Window preserves one screen, including the prompt line, of user-entered 
messages. When the end of the display screen is reached, the previous messages are 
overwritten, beginning at row one (the line below the prompt line). 


NOTE: Use the keyboard variables and the send_key routine 
explained in Section 72, Other Library Tools, to program the 
Run-mode use of 0 and 0 in the Display Window. (For other 
Run-mode screens, these keys control the playback speed of disk 
data.) 


(A) Variables 

There are variables accessible to the user which provide information about the 
Display Window. Table 64-2 lists the variables and their possible values. Two 
variables indicate the current position of the cursor: current Jine stores the row 
number and current_col stores the column number. To find out which attributes 
are active in the Display Window, check the values stored in window _color and 
window ^modifier. Color is stored in the high byte of the two-byte variable 
window_color. Enhancements are stored in the low byte. The current font code 
can be found in window _modifier . 


NOTE: Attributes assigned via the %m conversion specifier 
(refer to tracef- routine input) to characters in trace buffers will 
not alter the values of window_color and window ^modifier. These 
variables refer to the Display Window only. 


The variable display window _buffer provides the user with access to the 
display-window buffer. This variable is an array of 1,088 longs. Each element 
in the array contains one byte of character data and three bytes of attributes. 
The attributes are determined by the current values of window_color and 
window jnodifier. 
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Type Variable 

extern unsigned short currentjlne 

extern unsigned short current_col 

extern unsigned short wlndow_co!or 


i 
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Value (hex/decimal) Meaning 


o- 10/0-16 


0-3/10-63 


0 

1 

2 

3 

4 

5 

6 
7 


0 

8 

10/16 

10/24 

20/32 

20/40 

30/48 

38/56 


Contains the current row 
number of the cursor position In 
the Display Window. Line Setup 
configured for emulate or 
monitor mode. 

Contains the current column 
number of the oursor position In 
the Display Window. Line Setup 
configured for emulate or 
monitor mode. 

Two-byte variable. Current 
color selections are Indicated In 
the low byte. Current 
enhancements are Indloated In 
the high byte. Written to by %m 
conversions. Attributes are 
copied Into data words In 
Display Window. Line Setup 
configured for emulate or 
monitor mode. 

Isolate bits of Interest via 
bitwise ending (&) of mask with 
variable. Compare result to 
value column. For example, 
underline attribute mask = 

0x100. Therefore wlndow_color 
& 0x100 equals 0 (underline oft) 
or 0x100 (underline on). Line 
Setup configured for emulate or 
monitor mode. 

background color mask = 7 (bits 
1-3): 

black 

blue 

green 

cyan 

red 

magenta 

yellow 

white 

foreground color mask = 0x38 
(bits 4-6): 

black 

blue 

green 

cyan 

red 

magenta 

yellow 

white 
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Table 64-2 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


(wlndow_color continued) 

0 

40/64 


0 

80/128 


0 

100/256 


0 

200/512 


0 

400/1024 


0 

800/2048 


0 

1000/4096 


0 

2000/8192 


0 

4000/16384 


0 

8000/32768 


color blink mask « 0x40 (bit 7): 

no blink 
blink 

color strike- thru mask = 0x80 
(bit 8): 

no strike-thru 
strike-thru 

overllne mask = OxlOO (bit 9): 

no overllne 
overllne 

blank mask = 0x200 (bit 10): 

no blank 
blank 

underline mask = 0x400 (bit 
W: 

no underline 
underline 

reverse Image mask - 0x800 (bit 
12 ): 

no reverse Image 
reverse Image 

hex mask = OxIOOO (bit 13): 

no hex 
hex 

low Intensity mask = 0x2000 (bit 
14): 

no low Intensity 

low Intensity (RS-170 output) 

monochrome blink mask = 
0x4000 (bit 15): 

no monochrome blink 
monochrome blink 

monochrome strike-thru mask = 
0x8000 (bit 16): 

no monochrome strike-thru 
monochrome strike-thru 
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Table 64-2 (continued) 


Type 

Variable 

Value (hex/declmal) Meaning 

extern unsigned char 

wlndowjmodlfler 


Contains the current modifiers. 
Line Setup configured for 
emulate or monitor mode. 




font mask = 7 (bits 1-3): 



0 

ASCII 



1 

special graphic oharaoter set 
(refer to Table 64-5) 



2 

primary font — code selected on 
Line Setup 



3 

alternate font— current 
Implementation Is for call-setup 
phase In X.21 (ASCII) 



7 

hexadecimal 

extern unsigned long 

display window buffer [1068] 

Array of 32-blt words that make 




up the one-screen Display 
Window. Each word contains 




three bytes of attributes and a 
one-byte character. Refer to 
Table 64-4. Line Setup 
configured for emulate or 
monitor mode. 


(B) Structures 

Once the data word is written to the buffer as an element in the 
display _window_buffer array, it can be accessed and written to— and therefore 
changed— the same as any other location in memory. There is an extern array, 
display _windowJndex_buffer [17] , which provides a method of informing the 
display controller on the CPM card that the display needs to be updated. The 
structure of this array is shown in Table 64-3. 

Each element in the display_windowJndex_buffer array represents a horizontal 
row or line in the Display Window. Each element is a structure with two 
variables, mpm and cpm. The first variable in the structure, mpm, increments 
automatically whenever a line in the display-window buffer is updated by a 
display routine. (If you write to the buffer directly without using one of the 
display routines, you must increment this variable “manually.") Its particular 
value at any moment is not important. What is significant is whether or not the 
value of the second variable in the structure, cpm, is the same as mpm. The 
processor on the CPM compares these two variables (for each line) periodically 
to determine if a line in the Display Window needs to be rewritten. If the 
values of the two variables do not match, it means that a line updated in 
memory now needs to be updated by the CPM display-controller software. 

After the display is changed, the value of mpm is copied automatically into cpm. 
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Table 64-3 

Display Window Buffer Structures 


Type Variable Value (hex/decimal) 


Meaning 


Structure Name*. dlsplay_window_lndex_buffer [17J An array of structures used for detecting 

" changes to the display-window buffer, There are 

seventeen elements In the array, one for each 
line In the Display Window. When a change Is 
made to a line In the display-window buffer, the 
corresponding element In the array Is accessed. 

If a display f routine changes line 3, 
display_wlndow_ lndex_bulfer[3J.mpm Is 
automatically Incremented. The CPM detects 
the difference between 
dlsplay_wlrdowJndex_butfer [ 3l.mpm and 
dl$play_wlndowJndox_buffer (3j.cpm and 
updates* line 3 In the Display Window. Declared 
as type extern struct. 

You must Increment an mpm variable manually 
when you write directly (not via a display! routine) 
to the Display Window. 


unsigned char mpm O-tflO-255 When the MPM updates a line In the 

display-window buffer, this variable Is 
Incremented. 

unsigned char cpm O-t/IO-255 The CPM cheoks the value of this variable agalnBt 

the value of mpm. If they are different, the 
value In mpm is copied Into cpm. The updated 
line In MPM Is then presented on the 
display-window screen. 


(C) Routines 

You may position the cursor before output is generated on the screen via the 
pos_cursor and restore jcursor routines. The pos_cursor routine positions the 
cursor at the row and column you specify. The restore _cursor routine returns 
the cursor to a previous location. 

One routine, display/, allows you to add attributes to messages in the Display 
Window, including the prompt line. These attributes are listed in Table 64-4, 

Additional routines control the labeling of Display Window softkeys: 
set _dw Jkey Jabel, show_dw JkeyJabels, highlight _dw Jkey Jabel , and 
unhighlight_dw Jkey Jabel. 
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dlsplayc 

Synopsis 

extern void displayc(character); 
const char character; 

Description 

The displayc routine outputs a single ASCII character to the Display Window 
screen. The placement of the output on the screen may be controlled via the 
pos_cursor routine. Attributes may not be used in displayc. 

Inputs 

The parameter value may be given as a hexadecimal, octal, or decimal constant; 
as an alphanumeric constant inside of single quotes; or as a variable. A 
hexadecimal value must be preceded by the prefix Ox or OX; an octal value must 
be preceded by the prefix 0. If no prefix appears before the input, the number 
is assumed to be decimal. Valid numeric entries are 00 to 127, decimal. An 
alphanumeric character placed between single quotes will be output as is to the 
display. 

Example 

The displayc entries on the left output the character given on the right, at the 
cursor location on the Display Window screen: 


dtsplayc(‘a’)\ a 

displayc(65); A 

displayc(Ox65); e 

displayc(065); 5 


displayf 

Synopsis 

extern int dlsplayf(format _ptr, . . . ); 
const char * format _ptr; 

E<?$ 9 .ripti Q n 

The displayf routine writes output to the Display Window screen, under control 
of the string pointed to by format _ptr that specifies how subsequent arguments 
are converted for output. If there are insufficient arguments for the format, the 
behavior is undefined. If the format is exhausted while arguments remain, the 
excess arguments are evaluated but otherwise ignored. The displayf routine 
returns when the end of the format string is encountered. The placement of the 
output on the screen may be controlled via the pos_cursor routine. 
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Inputs 

The format is composed of zero or more directives: ordinary characters (not 
%), which are copied unchanged to the output stream; and conversion 
specifications, each of which results in fetching zero or more subsequent 
arguments. Each conversion specification is introduced by the character %. 

After the %, the following appear in sequence: 

• Zero or more flags that modify the meaning of the conversion specification. 
The flag characters and their meanings are: 

The result of the conversion will be left-justified within the field. 

+ The result of a signed conversion will always begin with a plus or 
minus sign. 

space If the first character of a signed conversion is not a sign, a space will 
be prepended to the result. If the space and + flags both appear, the 
space flag will be ignored. 

ft The result is to be converted to an “alternate form.” For d and i 

conversions, the flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a zero. For x (or 
X) conversion, a nonzero result will have Ox (or OX) prepended to it. 
For u conversions, the argument is displayed in small hex characters. 
For example, displayf (“%#u”, 258); yields °i° 2 . For c and s 
conversions, if the argument contains a newline character, it is 
displayed as V. 

• An optional decimal integer specifying a minimum field width. If the 
converted value has fewer characters than the field width, it will be padded 
on the left (or right, if the left adjustment flag, described above, has been 
given) to the field width. The padding is with spaces unless the field width 
integer starts with a zero, in which case the padding is with zeros. 

• An optional precision that gives the minimum number of digits to appear for 
the d, i, o, u, x, and X conversions, the maximum number of characters to 
be written from an array in an s conversion, or the number of characters to 
be written from an array in an H conversion (overriding the usual 
null-termination of strings). The precision takes the form of a period (.) 
followed by an optional decimal integer; if the integer is omitted, it is treated 
as zero. The amount of padding specified by the precision overrides that 
specified by the field width. 
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• An optional h specifying that a following d, i. o, u, x, or X conversion 
specifier applies to a short int or unsigned short int argument (the argument 
will have been promoted according to the integral promotions, and its value 
shall be converted to short int or unsigned short int before printing); or an 
optional 1 specifying that a following d, i, o, u, x, or X conversion specifier 
applies to a long int or unsigned long int argument. If an h or 1 appears 
with any other conversion specifier, it is ignored. 

• A character that specifies the type of conversion to be applied. (Special AR 
extensions have been added.) The conversion specifiers and their meanings 
are: 

d, i, o, u, x, X 

The int argument is converted to signed decimal (d or i), unsigned 
octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x 
or X); the letters abcdef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies the minimum 
number of digits to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with leading zeros. 

The default precision is 1. The result of converting a zero value with 
a precision of zero is no characters. 

c The int argument is converted to an unsigned char, and the resulting 
character is written. 

s The argument shall be a pointer to a null-terminated array of 8-bit 

chars. Characters from the string are written up to (but not including) 
the terminating null character: if the precision is specified, no more 
than that many characters are written. The string may be an array 
into which output was written via the sprintf routine. (If the string 
pointed to is an array which has been written via the stracef routine, 
you must use %b rather than %s to display it.) 
p The argument shall be a pointer to void. The value of the pointer is 
converted to a sequence of printable characters, in this format: 
0000:0000. There are always exactly 4 digits to the right of the 
colon. The number of digits to the left of the colon is determined by 
the pointer’s value and the precision specified. Use this conversion to 
display 80286 memory addresses. The 16-bit segment number will 
appear to the left of the colon and the 16-bit offset to the right. 

% A % is written. No argument is converted. 

\n Displays V. No argument is converted. When \n is not preceded by 
a %, it is not a conversion specifier. Instead of a V being displayed, a 
newline (Si^) will be executed. 

H displays a character array (pointed to by the argument) as small hex 
characters. If precision is specified, it is used as the length of the 
array (overriding the usual null-termination of strings). 
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b The argument shall be a pointer to an array of 32-bit words. 

Characters from the string are written up to (but not including) the 
terminating word containing a null character: if the precision is 
specified, no more than that many words are written. If the siring 
pointed to is an array into which output was written via the stracef 
routine, you must use %b rather than %s to display it. (To display 
the information in an array written to via sprintf, use %s.) 

m The argument is a long integer that indicates attributes to be assigned 
to subsequent characters. Attributes stay “on” until they are 
specifically turned “off" with, another %m conversion specifier. The 
lowest-order byte contains primarily font code. The next higher byte 
is not used to set attributes. (In the display-window buffer, this 
second byte is reserved for character coding,) The third byte holds 
color information. The high byte indicates which enhancements 
should be invoked. 

Attributes are written automatically to window _color and 
window jnodifier variables, then copied into subsequent 32-bit data 
words in the Display Window. Table 64-4 shows the format of this 
32-bit word. 

Attributes may not be assigned as a one-byte value. Even if you want 
to alter only one attribute setting, color for example, you must include 
it as part of a long. Append an “L” at the end of the hexadecimal 
code specifying attributes to indicate the value is a long. 

NOTE: If you are specifying an attribute in a lower-order byte of the 
long, color for example, and you want the high byte (or bytes) to be 
zero, you may omit the high byte provided you have the "L” 
appended at the end of the hexadecimal code. The high byte (or 
bytes) will be left-padded with zeroes. For example, Ox200000L is 
converted to Ox00200000L. Associated characters will be displayed 
on a color monitor as green on a black background, as dictated by the 
hexadecimal 20 in the third byte. Enhancements are controlled in the 
high byte, now assigned a value of zero. Any enhancements 
previously turned “on” will be turned “off.” 

If a conversion specification is invalid, the behavior is undefined. 

If any argument is or points to an aggregate (except for an array of characters 
using %s conversion or any pointer using %p conversion), the behavior is 
undefined. 

In no case does a nonexistent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is expanded to 
contain the conversion result. 
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Returns 

The display / routine returns the number of characters displayed. 

Exampfc 

To display a date and time in the form “Sunday, July 3, 10:02,” where weekday 
and month are pointers to strings: 

LAVER: 1 

{ 

unsigned char weekday [10]; 
unsigned char month [10J; 
unsigned short day; 
unsigned char hour; 
unsigned char min; 

) 

STATE: output_to_dlsplay_wlndow 
CONDITIONS: KEYBOARD ■ " 

ACTIONS: 

< 

display/] " %s, %s %d, %.2d:%.2d\n", weekday, month, day, hour, min); 

) 

sprintf 

The sprintf routine is similar to the display f routine, display f writes output with 
or without attributes directly to the Display Window, sprintf, fully documented 
in Section 67.3, writes output to a character array in which attributes are not 
supported. This routine is useful for writing formatted output to a display, 
printer, or file. 

See also stracef in Section 64.4(C). 
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Table 04-4 

Display Window/Trace Buffer 32— Bit Data Word 


Bit 

Mask {hex)t 

Input (hex) ft 

Meaning 




Modifier attributes, font for example, 
are contained In the low byte of the 
32 -bit word. 

1-3 

OOOOOOflZL 


Eflnt: 



OOOOOOQQL 

ASCII . 



OOOOOOfllL 

speolal graphic character set (refer to 
Table 64-5) 



OOOOOOQ2L 

primary font— oode selected on Line 
Setup 



OOOOOOG2L 

alternate font— current Implementation 
Is for call-setup phase In X.21 (ASCII) 



000000QZL 

hexadecimal 

4 

OOOOOOQSL 


Special character Indicator: 

(used In trace buffer only; should not 
be altered by user) 



oooooojjql 

only value In modifier In trace buffer 
header 



OOOOOOflfiL 

Character Is not dlsplayable but 
contains control Info used Internally by 
the trace loglo. When a “\n m 1s 
Included In a trace f routine, for 
example, a new line Is generated, but 
nothing Is displayed on the trace 
screen. The trace/ routine 
automatically sets this bit before the 
32-blt word Is written Into 
trace _but. array. 

5-8 

OQOOOOtQL 

OOOOOOGQL 

unused, but should be zero 

9-16 

OOOOtfOOL 

OOOOflQOOL 

Character data Is contained In the 
second byte of the long word. Input 
should be 00 In all %m conversions. 


f Us 0 the masks to change attributes of characters In the Display Window or trace buffer. In the Display Window, 
characters are represented In the second byte of the longs that comprise the 1,088 array elements In 
display _wlndow_buffer . In the f race_buf structure, the characters are represented In the second byte of the 
longs that make up the f race Jtuf .array. To change one attribute of a character while leaving the others 
unchanged: 

dlsplay_wtndow_bu!fer l position] = ((display _\Hindow_buller l position] & (-attribute-mask)) | Input); 

To change only the font of the twenty-first character In the trace buffer from Its current setting to the special 
graphic font, for example: 

t2jrbuf.array[20] = {[trace^buf. array! 20] & ( -0x00000007 L)) | 0x0000000 ILf ; 

And\ng the character with the mask will Indicate the current setting of an attribute: 

If ( I2jrbuf.array[20 ] 4 0x00000007i) equals 2, then the 21st character In the Trace 2 user-trace buffer Is 
being displayed In the font selected on the Line Setup menu. 

ft In display 1 routines, the %m conversion specifier writes Input to the wlndow_color and wlndow_modl/ler 

variables. These variables are copied Into subsequent data words In the Display Window. In trace/ routines, the 
%m conversion specifier writes Input to trace_buffer header. The header Is then copied Into each subsequent 
data word In the buffer. Combine attributes via hexadecimal addition. 
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Table 64-4 (continued) 


Bit Mask (hex) Input (hex) 


Meaning 


Color Is contained In the third byte of 
the long. Combine color attributes via 
hexadecimal addition. 


17-19 00QZ0000L 


Background color : 


OOfiQOOOOL 

OOQIOOOOL 

OOfiQOOOOL 

OOQfiOOOOL 

OOQiOOOOL 

OOQfiOOOOL 

OOQfiOOOOL 

OOQZOOOOL 


black 

blue 

green 

cyan 

red 

magenta 

yellow 

white 


20-22 OOfiflOOOOL 


Foreground color : 


OOQfiOOOOL 

OOQflOOOOL 

OOIQOOOOL 

OOISOOOOL 

OOQQOOOOL 

002B0O00L 

OOfiQOOOOL 

ooaaooooL 


black 

blue 

green 

cyan 

red 

magenta 

yellow 

white 


23 004Q0000L 


Color blink : 


OOQQOOOOL no blink 

OOiQOOOOL blink 


24 OOfiQOOOOL 


Color strike-thru : 


OOfiQOOOOL 

OOfiQOOOOL 


25 QiOOOOOOL 


QQOOOOOOL 

QIOOOOOOL 

26 QQOOOOOOL 

QQOOOOOOL 

QQOOOOOOL 

27 QiOOOOOOL 


no strike-thru 
strike-thru 

Enhance attributes, underlining for 
example, are contained In the high 
byte of the long. Combine 
enhancements via hexadecimal 
addition. 

Oyerline ; 

(for monochrome and color) 

no overline 
overllne 

Blank ; 

monochrome display, color display 
monochrome no display, color display 

Underline : 

(for monochrome and color) 


QQOOOOOOL 

QiOOOOOOL 


no underline 
underline 
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Table 64-4 (continued) 


Bit 

Mask (hex) 

Input (hex) 

Meaning 

28 

QflOOOOOOL 


Monochrome reverse Image: 



QfiOOOOOOL 

no reverse Image 



QfiOOOOOOL 

reverse Image 

29 

1QOOOOOOL 


Hex: 



qqooooool 

no hex 



1QOOOOOOL 

hex 

30 

2QOOOOOOL 


Monochrome low Intensity; 



QfiOOOOOOL 

no low Intensity 



QQOOOOOOL 

low Intensity (RS-170 Interface) 

31 

4Q000000L 


Monochrome blink: 



QfiOOOOOOL 

no blink 



4Q000000L 

blink 

32 

QfiOOOOOOL 


Monochrome strike-thru: 



QfiOOOOOOL 

no strike-thru 



QfiOOOOOOL 

strike-thru 
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Table 64-5 

Special Graphic Character Sett 


Display 

Input (hex/decimal) 

Display 

Input (hex/decimal) 

T. 

0 

— 

lc/28 

S 

1 

1 

1 d/29 

— 

2 

T 

1e/30 

— 

3 

JL 

If/31 

)) 

4 

H 

20/32 

« 

5 

h 

21/33 

J7. 

6 

i 

22/34 

m 

7 

1 

23/35 

a 

a 

■ 

24/36 

0 

9 

1 

25/37 

□ 

a/10 

i 

26/30 

0 

b/11 

1 

27/39 

□ 

c/12 

1 

28/40 

0 

d. 11/13, 17 

•S 

$ 

29/41 


e/14 

1 

2a/42 


f/15 

s* 

2b/43 

• 

10/16 

m 

2o/44 

1 

12/10 

■ 

2d/45 

J 

13/19 


2e/46 

*" 

14/20 


2f/47 


15/21 

■ 

30/46 

H 

16/22 

/space) 

31/49 

J 

17/23 

t 

32/50 

L 

18/24 

4- 

33/51 

r 

19/25 

4- 

34/52 

i 

1a/26 

-► 

35/53 

+ 

lb/27 

— 

36/54 


f Written to the Display Window or a trace buffer when low (modifier) byte of 32-blt data word = 0x01 . 


JUL ’90 


64-17 





INTERVIEW 7000 Series Advanced Programming: ATLC-1 07-951 -108 


Table 64-5 (continued) 

Display 

Input (hex/decimal) 

Display 

Input (hex/declmal) 

¥ 

80/128 

D 

9a/154 

a 

81/129 

y 

9b/ 155 

r 

82/130 

z> 

90/166 

j 

83/131 

X 

9d/157 

> 

84/132 

te 

9e/158 

• 

85/133 

V 

91/169 

5 

86/134 

5> 

a0/160 

T 

87/135 

f 

al/161 

-/ 

88/136 

'ii 

a2/162 

•5 

89/137 

t 

a3/163 

I 

8a/138 

h 

a4/164 

* 

8b/139 


a5/166 


80/140 

— 

a6/166 

n 

8d/1 41 


a7/167 

3 

8e/142 


ae/168 

'J 

8f/143 

j 

a9/169 

- 

90/144 

;i 

aa/170 

7 

91/145 

t 

ab/171 


92/146 

~> 

ac/172 


93/147 

'S 

ad/173 

I 

94/148 

* 

ae/174 

il 

95/149 

"7 

af/175 

1) 

96/150 


b0/176 

* 

97/151 

A 

bi/177 

0 

98/152 


b2/178 

*T 

99/153 

=E 

b3/179 
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Table 64-5 (continued) 


Display 

Input (hex/declmal) 

Display 

Input (hex/decimal) 

P 

b4/1 80 

ft 

ce/206 

1 

b5/18l 

A 

of/207 

3 

b6/102 

£ 

d0/208 

V 

b7/183 

s 

di/209 

'J 

b8/184 

(€ 

d2/210 

lb 

b9/185 

6 ' 

d3/21 1 

U 

ba/186 

o 

d4/212 

□ 

bb/187 

6 

d5/213 

□ 

bo/188 

u 

d6/2l4 


bd/189 

u 

d7/21S 

Yt 

be/190 

9 

de/216 

• 

bf/191 

0 

d9/217 

<? 

cO/192 

u 

da/218 

Ci 

Cl/193 

<D 

db/219 

e 

C2/194 

£ 

dc/220 

a 

C3/195 

Q 

dd/221 

a 

C4/196 

R 

de/222 

a 

C5/197 

/ 

df/223 

a 

C6/198 

a 

eO/224 

e 

C7/199 

i 

el/225 

e 

C8/200 

6 

e2/226 

# 

C9/201 

u 

e3/227 

e 

ca/202 

n 

e4/228 

T 

cb/203 

N 

05/229 

i 

cc/204 

a 

e6/230 

i 

cd/205 

o 

e7/231 
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Table 64-5 (continued) 


Display 

Input (hex/decimal) 

Display 

Input (hex/decimal) 

6 

e8/232 

i 

ed/237 


e9/233 


ee/236 

— i 

ea/234 

s 

ef/239 

4 

eb/235 

• 

f0/240 

A 

ec/236 




displays 

Synopsis 

extern void displays (string_ptr ) ; 
const char * string_ptr; 

Description 

The displays routine writes output to the Display Window screen, under control 
of the string that is pointed to by string_ptr. The displays routine returns when 
the end of the string is encountered. The placement of the output on the screen 
may be controlled via the pos_cursor routine. Attributes may not be used in 
displays. 

Inputs 

The input is a pointer to a string composed of zero or more ordinary characters. 
Octal or hexadecimal values also may be included in the string, with octal 
preceded by \ and hex by \x. Pad each value to three integers with leading 
zeroes. 

Example 

The following entry 

pos_cursor( 0, 0 ); 
displays!" End of lest. 

produces the following output on the prompt line: 

End of test. 

The following coding produces the same output: 

pos_cursor( 0, 0 ); 
const char ' string_ptr; 

String_ptr = “End of test."; 
displays (string_ptr); 
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dIsplay_prompt 

S yp .opsig 

extern void display _prompt(stringj>tr); 
const char * slrlng_ptr; 

Description 

The display _prompt routine displays a designated string at the beginning of the 
prompt line. The cursor is automatically positioned at row zero, column zero. 
Once the prompt . is. written, the..cursot is returned to its previous position. The 
softkey equivalent of this routine is the PROMPT action. The prompt is visible on 
whichever display screen is active at the time the prompt is written. The most 
recent prompt is retained in the Display Window. Attributes may not be used in 
display _prompt. 

Inputs 

The input is a pointer to a string composed of zero or more ordinary characters. 
Octal or hexadecimal values also may be included in the string, with octal 
preceded by \ and hex by \x. Pad each value to three integers with leading 
zeroes. 

Example 

Refer to the example provided for the displays routine. The same string could 
be output to the same position without calling the pos_cursor routine: 

display _prompt("End of test. 


or 


const char * string_ptr; 
strlng_plr = "End of test."; 
display_prompt (strlng_ptr); 


pos_cursor 

Synopsis 

extern unsigned ini pos_cursor(row, column); 
unsigned char row; 
unsigned char column; 

Description 

This routine positions the cursor on the Display Window screen by row and 
column numbers. 

NOTE: The pos_cursor routine may not be used to position the 
cursor on trace screens. 
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Inputs 

The first parameter is the row number. Possible values: 0-16. (The top line of 
the screen is reserved for header information and cannot be written to.) 

The second parameter is the column number. Possible values: 0-63. 

Returns 

The posjcursor routine returns the previous cursor position in the form of an 
unsigned int. The high byte contains the row number; the low byte identifies the 
column number. 

Example 

To position the cursor at the far left edge of the prompt line on the Display 
Window, enter zero for both parameters. 

LAYER: 4 

STATE: wrlte_to__dlsplay 

CONDITIONS: KEYBOARD * " 

ACTIONS: 

{ 

pos_cursor(0,0) ; 

displays!" Display on prompt line."); 

) 

restore_cursor 

Svnonsis 

extern void resiore_cursor(position); 
unsigned Int position ; 

Description 

The restore jsursor routine returns the cursor to a previous position. 

NOTE: The restore ^cursor routine may not be used to position 
the cursor on trace screens. 


Inputs 

The only input is an unsigned int in the same form that is used by the returned 
value of the pos_cursor routine. The high byte identifies the row number. The 
low byte identifies the column number. 

Example 

Suppose the cursor is located in the middle of the Display Window. You want 
to write a message to the prompt line, but return to your previous location on 
the screen to continue your display. 
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{ 

unsigned Ini previous; 

) 

STATE: display 

CONDITIONS: KEYBOARD “ ” 

ACTIONS: 

{ 

pos_cursor(8,0); 

displays (“This line begins on row 8, column 0 of the Display Window."); 

previous = pos_cursor(0,0); 

dlsplays(“This sentence is on the prompt line."); 

restore ^cursor (previous ) ; 

displays(“This sentence begins on row 8, column 58 of the Display Window, the 
position of the cursor at the time pos_cursor(0,0 ) was called.’’); 

) 

set_dw_fkey_label 

S^nQPSig 

extern void sel_dw Jkey_label(fkey, label _ptr); 
unsigned int fkey; 
const char • label _ptr; 

Description 

The set_dw JkeyJabel routine assigns a user-defined label to a specified Display 
Window softkey. A call to set_dw _Jkey_label does not automatically update the 
label on the Display Window screen. You must press the Run-mode DSP WND 
softkey at least once to access the new rack of softkey labels. After that, you 
may update the display by calling the show _dvtjkey_l<ib els routine. 

You may monitor the softkeys associated with your labels only when the 
user-defined rack of softkeys is active, i.e., the labels are displayed. When the 
labels are displayed and a function key pressed, the fast-event variable 
keyboard _new_any_key comes true and the variable keyboard _any_key is updated 
according to the values listed below. See Section 72.2 for more information on 
these variables. 


Hex Value 

197 

198 

199 
19a 
19b 
19c 
19d 
I9e 


Kev Pressed 

0 

m 

m 

0 

(EH 

HU 

0 

HD 


There is no Protocol Spreadsheet softkey equivalent of this routine. 
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Inputs 

The first parameter identifies the number of the function key to be labeled. 
Integers from 1 through 8 are valid values. If the specified value is out of the 
valid range, the label is not assigned to any softkey. 

The second parameter is a pointer to a null-terminated string, i.e., the label that 
should appear below the designated softkey. The label string has a maximum 
length of seven characters. If it has fewer than seven characters, it is padded to 
the right with spaces. If it has more than seven characters, only the first seven 
are used. 

Example 

In the example below a label is assigned to each of the softkeys in the Display 
Window. To see the labels displayed, press DSP WND. 

LAYER: 1 

STATE: deflnejabels 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

setjiw _fkeyjabe!(l , “ one"); 
setjiw JkeyJabel(2, " two’’); 
setjiw JkeyJabel(3, " three"); 
setjiw __ JkeyJabet(4 , " four"); 
setjiw Jkey_label(5, “ five"); 
setjiw Jkey_labe!(6, “ six"); 
setjiw _fkey label(7, “ seven"); 

} 

show_dw_fkey_!abels 

Synopsis 

extern void showjiw _fkey_labels(); 

Description 

The show_dwJ~keyJabels routine updates the display of all user-assigned softkey 
labels in the Display Window. For this routine to have any effect, the DSP WND 
softkey must have been pressed at least once and the user-assigned labels must 
be currently displayed. There is no Protocol Spreadsheet softkey equivalent of 
this routine. 

Example 

Enter the Display Window by pressing DSP WND in Run mode. Then alternate 
between two defined softkey rack by pressing HD (labeled MORE) from either 
rack. 

{ 

extern fast_event keyboard jtew jiny _key; 
extern volatile unsigned short keyboard jtny key; 

} 
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LAYER: 1 

STATE: flrst_rack 

CONDITIONS: ENTER STATE 
ACTIONS: 

{ 

setjiw JkeyJabel (! , “ one"); 
setdw Jkey_label(2, “ two"); 
setjiwjkeyiabet(3, " three"); 
setjiw _Jkey_label(4, “ four"); 
setjiw _JkeyJabel(5, * five"); 
set_dw JkeyJabel(6, “ six"); 
setjiw _fkey_label(7, “ seven"); 
setjiw Jkey_labe{(8, “ MORE"); 
showjiw _fkey_iabets(); 

) 

NEXT_STATE: second_rack 
STATE: second_rack 
CONDITIONS: 

< 

keyboard new anyjtey && (keyboard jiny key -= 0xl9e) /* MORE pressed on rack 1 V 

) 

ACTIONS: 

{ 

setjiw JkeyJabel(l, " eight"); 
setjiw _fkeyjabel(2, “ nine"); 
setjiw_fkeyjabel(3, “ ten"); 
seljiw_fkey_label(4, " eleven"); 
setjlw_fkeyJabel(S, “ twelve"); 
setjiw JkeyJabel(6, " thirtn"); 
setjiw _Jkey_label(7, * fourin"); 
setjiw JkeyJabel(8, " MORE"); 
showjiw JktyJabelsQ; 

} 

NEXT_STATE: walt_for_mor 0 
STATE: walt_for_more 
CONDITIONS: 

{ 

keyboard _new_any_key <&& (keyboard any_key == 0xI9e) I * MORE pressed on rack 2 */ 

) 

NEXT STATE: first rack 


highlight_dw_fkey label 

Syoopsis 

extern void highlight _dw Jkeylabel (/key) ; 
unsigned Int /key; 


Description 

The highlight jd\v_Jkey_Iabel displays a specified user-defined softkey label in 
reverse video. This routine applies to the Display Window only. There is no 
Protocol Spreadsheet softkey equivalent of this routine. 
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Inputs 

The only parameter identifies the number of the function key whose label is to 
be highlighted. Integers from I through 8 are valid values. Values outside this 
range are ignored. 


Examp le 

This example is similar to the one for showjfw JkeyJabels except that each 
time a softkey is pressed, its label is highlighted and any previous highlighted 
label is returned to normal video, 

{ 

extern fast^event key board _newany_key; 

extern volatile unsigned short keyboard jiny_key; 

unsigned short current Jkey; /* currently highlighted fkey label V 

} 

LAYER: 1 

STATE: flrst_rack 

CONDITIONS: ENTER_STATE 
ACTIONS: 

1 

unhighlight jdw Jkey_label(current Jkey); 
sel_dw Jkey_label(l , “ one"); 
setjdw Jkey_iabel(2, " two"); 
setjdw JkeyJabel(3, " three"); 
setjdw Jkey_label(4, " four"); 
setjdwJkey_label(S, " five"); 
set_dw Jkey_label(6, “ six"); 
set_dw Jkey_label(7, “ seven”); 
set_dw_fkey_label(8, " MORE"); 

current Jkey = 0; /* 0 not in range — no fkey highlighted */ 
showdw _fkey_labels(); 

} 

NEXT_STATE: secondj-ack 
STATE: second_rack 
CONDITIONS: 

{ 

keyboard_new any_key <St& (keyboard _any_key == 0xl9e) MORE pressed on rack 1 V 

} 

ACTIONS: 

{ 

unhighlight_dw _Jkey_i a bei (current Jkey); 

current Jkey = 0; /* no highlight on initial display of rack 2 */ 

setjdw JkeyJabelfl, “ eight’’); 

setjdw Jkey_label(2, “ nine"); 

set_dw JkeyJabel(3, “ ten"); 

setjdw JkeyJabel(4, “ eleven"); 

setjdw JkeyJabel(5, " twelve’’); 

setjdw JkeyJabel(6, “ thirln"); 

set_dw JkeyJabel(7, “ fourtn"); 

setjdw Jkey_label(8, “ MORE"); 

show dw JkeyJabelsQ; 

} 
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NEXT_STATE: wait for_more 
CONDITIONS: 

{ 

/•key other than MORE pressed on rack 1*1 

keyboard _new_any_key &&. ((keyboard_any_key >- 0x197) && (keyboard_any_key <- 
0xI9d)f 

} 

ACTIONS: 

{ 

unhlghlight_dw JkeyJabel (current Jkey); 
current Jkey = keyboard _any_key - 0x196; 
hlghllght_dw Jkey Jabel (current Jkey); 

) 

STATE: walt_for_more 
CONDITIONS: 

{ 

/* key other than MORE pressed on rack 2 *1 

keyboard _new_any_key && ( (keyboard _anyjcey >= 0x197) <5 <4 (keyboard _any_key <- 
0xl9d)J 

) 

ACTIONS: 

{ 

unhlghlight^dw JkeyJabel(current Jkey); 
current Jkey = keyboard _any_key - 0x196; 
highlight dw Jkey Jabel (current Jkey); 

) 

CONDITIONS: 

1 

keyboard _new_any_key && (keyboard_any_key == 0xl9e) /* MORE pressed on rack 2 */ 

) 

NEXT STATE: first rack 


unhighllght_dw_f key Jabel 

Synopsis 

extern void hlghlight_dw Jkey Jabel (Jkey); 
unsigned ini Jkey; 

Description 

The unhighlight _dw Jkey Jabel displays a specified user-defined softkey label in 
normal video. This routine applies to the Display Window only. There is no 
Protocol Spreadsheet softkey equivalent of this routine. 

Inputs 

The only parameter identifies the number of the function key to be 
unhighlighted. Integers from 1 through 8 are valid values. Values outside this 
range are ignored. 


JUL '90 


Example 

See highlight jlw Jkey Jabel. 
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64.4 Program and User Traces 

Unless their sizes are increased, Program Trace and the User Traces retain a 
maximum of 4096 characters, equivalent to four full screens when every character 
space is used. (See Section (B)2. below on increasing the size of trace buffers.) 
When a buffer's limit is reached, new characters written to the end of the buffer 
force out the same number of characters from the beginning of the buffer. The 
prompt line is not part of these buffers. Messages are appended to the end of the 
buffers. In Freeze mode you may scroll through the buffer using the cursor keys. 

You write messages to the User Traces only by using C routines. The Run-mode 
softkeys for User Traces-USER TR, TRACE 1, TRACE 2, TRACE 3, TRACE 4, TRACE 5, 
TRACE 6, TRACE 7— appear when the buffers are used in a program. 

(A) Variables 

There are no extern variables associated exclusively with Traces. 

(B) Structures 

1. Declaring trace buffers. The trace routines that write to any of the trace 
buffers require a pointer to the appropriate trace buffer as input. To point 
to one of the trace buffers, you must first have declared it as a structure, 

The structure that is common to trace buffers is named tracejbuf. This 
structure is already declared in a file called trace_buf.h located in the 
HRDIsysl include directory. The tracejbuf structure contains another 
structure, trace _buffer_header, which also is declared in the trace_buf.h file. 
(These structures are explained in Table 64-6.) Use the # include 
pre-processor directive to include both declarations in your program. 

There are eight trace buffers available (including the Program Trace), each 
one having its own display screen. All are instances of the trace _buf 
structure. Declare each one you use as an extern struct, as in this example: 

extern struct lrace_buf tl_irbuf; 

The names of all the trace buffers are listed in Table 64-6. 

2. Sizing trace buffers. There is a preprocessor ttpragma which allows the user 
to configure the size of the data array in each user trace buffer. The syntax 
is TRACE-NUMBER SIZE TRACE-NUMBER SIZE. . . . Trace number 0 
refers to the Program Trace buffer, and trace-number allows all 
trace-buffer arrays to be set at once. All sizes are given in terms of 
four-byte array elements, 
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The example below first sets all trace-buffer arrays to 16,000 elements, and 
then down-sizes array number 3 to 2,048 elements. 

ttpragma tracebuf * 16000 3 2048 

When a trace buffer is declared, its array will have the size specified in the 
ttpragma tracebuf directive. If the buffer was not referenced in a ttpragma 
tracebuf directive, its array size will default to 4,096. The maximum size for 
a trace-buffer array is 16,381 elements. If you specify a size that is too 
small or too large, an error message will be displayed. 
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Table 64-6 

Trace Buffer Structures 


Type 

Variable 

Value (hex/decimal) 

Meaning 


Structure of a header for trace buffers. 

Declared as type extern struct. Declared 
automatically If a softkey-entered TRACE action 
Is taken. Contained In the structure of the trace 
buffer. Declaration contained In file named 
HRD t syst Include I trace _buf.h. Written to by %m 
conversion specifier. 

Because It Is an extern structure, values of 
component variables should not be altered 
directly by the user. In some Instances, e.g., 
altering array size, the result could be a crash. 


unsigned short 

loglcal_end 

0-/I//0-4095 

end of data within the buffer. Maximum value Is 
one less than the arrayjslze. 

unsigned short 

logleal_end_wrap_count 

0 

non-zero 

trace buffer Is not full 

trace buffer Is full. As new lines are written to 
the end of the trace buffer, lines at the beginning 
of the buffer are removed. 

unsigned char 

modifier 


Special-character Indicator bit and bit 8 must be 
zero. For other speclflo values and their 
meanings, see Table 64-4. 

unsigned char 

color 

0- II 10-255 

For speclflo values and their meanings, see 
Table 64-4. 

unsigned char 

enhance 

0-fll0-255 

For specific values and their meanings, see 
Table 64-4. 

unsigned short 

write Jock 

0-fll/l/0-65535 

prevents two processes from writing to the same 
buffer at the same time. Should not be altered 
by user or future aocess to the trace buffers 
may be locked out. 

unsigned short 

array_slze 

1000/4096 

size of buffer: at present only one value 

unsigned char 

llneslze 

0-3/10-63 

number of characters In last line In buffer 

unsigned char 

9 pare 

0 

reserved for future use 


Structure of a trace buffer. Declared as type 
extern struct. Declared automatically If a 
softkey-entered TRACE action Is taken. 
Declaration contained In file named 
HRD Isysl Include I trace _buf. h. 

structure of the trace-buffer header described 
above 

array of data words In the buffer 
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Table 64-6 (continued) 


Type Variable Value (hex/decimal) Meaning 


Structure Name: progjrbuf 


struct trace_buffer_header hdr 
unsigned tong array (4096) 


Structure of the Program Trace buffer, an 
Instance of the trace_buf structure declared In 
file named HRDIsysllncludeltrace_bul.h. 
Declared as type extern struct lrace_but. 
Declared automatically If a softkey-entered 
TRACE action Is taken. Writing to this buffer 
makes the Run-mode PROG TR softkey appear, 

structure of the trace-buffer header described 
above 

array of data words In the buffer 


Structure Name: I1_trbuf 


struct trace_buffer_header hdr 
unsigned long array |4096) 


Structure of one of seven user trace buffers, an 
Instance of the trace_buf structure declared In 
file named HRD I sys I Include t trace _but.h. 
Declared as type extern struct trace_buf. 

Writing to this buffer causee the Run-mode 
TRACE 1 softkey appear. 

structure of the trace-buffer header described 
above 

array of data words In the buffer 


Structure Name: I2_trbuf 


struct trace_buffer_header hdr 
unsigned long array (4096] 


Structure of one of seven user trace buffers, an 
Instance of the trace_bul structure declared In 
file named HRDIsysllncludeltrace_but.h. 
Declared as type extern struct trace_but. 

Writing to this buffer causes the Run-mode 
TRACE 2 softkey appear. 

structure of the trace-buffer header described 
above 

array of data words In the buffer 


Structure Name: 13 trbuf 


struct trace_buffer_header hdr 
unsigned long array [4096] 


Structure of one of seven user traoe buffers, an 
Instance of the trace_bu( structure declared In 
file named HRDIsysllncludeltrace_but.h. 
Declared as type extern struct trace_but. 

Writing to this buffer causes the Run-mode 
TRACE 3 softkey appear. 

structure of the trace-buffer header described 
above 

array of data words In the buffer 


Structure Name: 14 trbuf Structure of one of seven user trace buffers, an 

' Instanoe of the trace but structure declared In 

file named HRDIsystlncludellrace_but.b. 
Declared as type extern struct trace_buf. 

Writing to this buffer oauses the Run-mode 
TRACE 4 softkey appear. 

struct trace buffer header hdr structure of the trace-buffer header described 

above 

unsigned long array [4096] array of data words In the buffer 
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Table 64-6 (continued) 


Type Variable Value (hex/decimal) 

Meaning 


( 


Structure Name: 15 trbuf Structure of one of seven user trace buffers, an 

Instance of the trace_bul structure declared In 
file named HRD/sy$/lncludenrace_buf.h. 
Declared as type extern struct trace_buf. 

Writing to this buffer causes the Run-mode 
TRACE 5 softkey appear. 


struct trace_buffer_header hdr 


structure of the trace-buffer header described 
above 


unsigned long array [4096] 


array of data words In the buffer 


Structure Name: 16 trbuf Structure of one of seven user trace buffers , an 

Instance of the trace_buf structure declared In 
file named HRD I sys / Include I trace _but.h. 
Declared as type extern struct trace_buf. 

Writing to this buffer causes the Run-mode 
TRACE 6 softkey appear. 


structure of the trace-buffer header described 
above 

array of data words In the buffer 


struct trace_buffer_header hdr 
unsigned long array [4096] 


Structure Name: 17 trbuf Structure of one of seven user trace buffers, an 

Instance of the trace_but structure declared In 
file named HRD Isysl Include Hrace_buf.h, 
Declared as type extern struct trace_bu/. 

Writing to this buffer causes the Run-mode 
TRACE 7 softkey appear. 


struct trace_buffer_header hdr 


structure of the trace-buffer header described 
above 


unsigned long array [4096] 


array of data words In the buffer 


(C) Routines 

Most routines defined below are valid for either the Program Trace or the user 
traces. One, however, applies to the user traces only. set_utrace JkeyJabel 
allows the programmer to modify the current softkey labels for the user traces, 

The other four trace routines— tracec, trace f, stracef, and traces— apply to both 
the Program Trace and the user traces. The softkey TRACE action is built on 
the trace f routine. 


64-32 


JUL ’90 





64 Display Window and Trace 


The first argument in three of these trace routines is the address of the trace 
buffer into which you want output written. Each time you call a trace routine, 
trace f for example, variables in the named trace-buffer structure are updated. 
Those variables which store attributes are updated when the %m conversion 
specifier is used in the trace f routine parameter. When %m is not present, the 
routine applies the attributes currently stored in the color, modifier, and enhance 
variables. 

The second argument in ail four of these trace routines is the character, string, 
or format pointer to the data that will be written to the selected trace buffer. 

The trace f routine allows you to add attributes to messages on the Program 
Trace screen and User Traces. These attributes are listed in Table 64-4. 

Each trace operation appends output to the end of the trace buffer. You may 
not use the posjcursor routine to position the cursor on any trace screen. New 
lines (or blank lines) may be generated via the “\n” nonliteral. Put the “\n” 
nonliteral at the end of the string to generate a leading blank line on the 
selected trace screen: 

tracef(&prog_lrbuf, “This trace message will generate a leading blank line.\n"); 

During real-time display, this line moves just ahead of the freshest trace message 
and continuously overwrites the oldest one. If you put the “\n” sequence at the 
beginning of the format string, no leading blank line will help you distinguish 
new messages from the old: 

traceff&progjrbuf, "\nThis message will not generate a leading blank line.”); 


tracec 

S yru op sia 

extern void tracec(trace_buffer jtr, character); 
extern struct trace_buf * tracejbuffer _ptr; 
const char character; 


The tracec routine outputs a single ASCII character to the trace screen 
indicated. 

Inputs 

The first parameter is a pointer to the trace buffer into which the character will 
be written. 

For the second parameter, see the displayc routine. 
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Example 

In this instance, output will be written to the Program Trace screen. 

{ 

If Include <trace_buf. h> 

extern struct trace buf prog trbuf; 

) 

LAYER: 2 

STATE: display to_prog_tr 

CONDITIONS: KEYBOARD * * 

ACTIONS: 

{ 

tracec (Aprogjrbuf, 'a’)\ 
tracecf Aprogjrbuf, '\n ’) ; 
tracecf Aprogjrbuf ,65 ) ; 
tracecf Aprogjrbuf, '\n ‘) ; 
tracecfAprogtrbuf, 0x65); 
tracecf Aprogjrbuf, ‘\n’); 
tracecfAprogjrbuf, 065 ) ; 

} 

When the user views the PROQ TR screen, the output will look like this: 

a 

A 

e 

5 

tracef 

Synopsis 

extern Int tracef (trace buffer _ptr, format _ptr, . . . ); 
extern struct trace_buf * trace_buffer _ptr; 
const char ’ format _ptr; 

Description 

The tracef routine writes output to a specified trace screen, under control of the 
string, pointed to by format _p/r, that specifies how subsequent arguments are 
converted for output. If there are insufficient arguments for the format, the 
behavior is undefined. If the format is exhausted while arguments remain, the 
excess arguments are evaluated but otherwise ignored. The tracef routine 
returns when the end of the format string is encountered. 

Inputs 

The first parameter is a pointer to the trace buffer into which the output will be 
written. 

For the second parameter, see the displayf routine. Placement of "\n” in the 
format string of a call to tracef generates a blank new line on the selected trace 
screen. (In a displayf routine, the newline character does not blank the new 
line.) 
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Attributes are written via the %m conversion specifier to trace Jyuf.hdr. modifier, 
trace _buf.hdr .color, and trace _buf.hdr. enhance. The attributes are copied from 
these variables into subsequent 32-bit data words in the Program Trace and User 
Traces. Table 64-4 shows the format of this 32-bit word. 


Returns 

The trace f routine returns the number of characters displayed, or a negative 
value if the unit is in freeze mode. 


Example 


This program traces X.29 PAD-control messages in DTE and DCE data packets. 
The letters “DCE” are underlined in the DCE trace lines. 


LAYER: 3 

{ 

((Include <trace_buf.h> 

extern struct trace_buf I3_trbuf; 

extern unsigned char * m jacket Jnfo jtr; 

extern unsigned short m jacket Jen; 

unsigned char padjtrl msg; 

) 

STATE: packetjype 

CONDITIONS: DTE DATA Q= 1 
ACTIONS: 

{ 

padjtrljnsg = m jacket Jnfo jtr(0]; 

trace f (&l3jrbuf, “DTE LCN: % . 3x PAD MSG: % ,2x\n" , m jacketjcn, 
padjtrljnsg); 

} 

CONDITIONS: DCE DATA Q= 1 
ACTIONS: 

{ 

pad ctrl_msg = m jacket info JirfO]; 

tracef ( &l3jrbuf , "%mDCE%m LCN:%.3x PAD MSG:%.2x\n", 0x040000001, 
OxOOOOOOOOL, m jacket Jen, padjtrljnsg); 

) 


stracef 


Synopsis 


extern void stracef (array Jtr, string Jtr) ; 
unsigned tong array jtr; 
const char * string jtr; 


Description 

The stracef routine is similar to the tracef routine, except that stracef writes 
output to a variable, while tracef writes output to a trace screen. The output is 
under control of the string pointed to by stringjytr that specifies how subsequent 
arguments are converted for output. If there are insufficient arguments for the 
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format, the behavior is undefined. If the format is exhausted while arguments 
remain, the excess arguments are evaluated but otherwise ignored. The stracef 
routine returns when the end of the format string is encountered. 

The stracef routine differs from sprintf in that it generates an array of longs, 
whereas sprintf generates an array of chars. When the stracef array is written to 
a trace buffer (or to the Display Window) it carries its predefined attributes 
along with it. An sprintf array, by contrast, will receive the attributes that are 
active in the buffer at the moment. 

At the end of the output string, there will be a null character with the Special 
Character Indicator bit set in its modifier attribute-byte. 

Inputs 

The first parameter is a pointer to the variable into which output will be written. 
The array which will hold output must be declared as a long. By allocating 32 
bits for each element, the array may accommodate attributes assigned via the 
%m conversion specifier. Attributes comprise 24 bits of the long. The preferred 
form of the declaration is unsigned long name (100). The size and name of the 
array are user-determined. 

For the second parameter, see the displayf routine. 


Example 


This program traces X.29 PAD-control messages for DTE and DCE data 
packets. The resulting trace is identical to the one generated by the example 
under tracef. Note that attributes that are turned on in an stracef array do not 
need to be turned off after the array has been brought, via the %b conversion 
specifier, into a tracef format string. 


LAYER: 3 

{ 

ft include <trace_buf.h> 

extern struct trace_buf I3_trbuf; 

extern unsigned char * m jacket Jnfo jtr; 

extern unsigned short m jacket Jen; 

unsigned char padjtrljnsg; 

unsigned long source [4]; 

) 

STATE: packet type 

CONDITIONS: DTE DATA Q= 1 
ACTIONS: 

{ 

stracef (source, “%s”, “DTE"); 

) 

NEXT STATE: pad_msg_trace 
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CONDITIONS: DCE DATA Q= 1 
ACTIONS: 

{ 

stractf (source, “%m%s", Ox04000000L, “DCE’'): 

) 

NEXT_STATE: padjn8g_trace 
STATE: pad_msg_trace 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

pad_ctrl_msg - m jacket Jnfo _ptr[0); 

trace/ (&l3jrbuf, “%b LCN:%.3x PAD MSG:%.2x\n" , source, m jacket Jen, 
pad Ctrl msg); 

) 

NEXT_STATE: packs tjype 


traces 

Synopsis 

extern void lraces(tracej>uffer jtr, stringjtr ); 
extern struct trace_buf tracejbuffer jtr; 
const char * string jtr; 


Description 

The traces routine writes output to a specified trace screen, under control of the 
string that is referenced by string j)tr. The traces routine returns when the end 
of the string is encountered. 


Inputs 

The first parameter is a pointer to the trace buffer into which the output will be 
written. 

For the second parameter, see the displays routine. 

Example 

In this instance, output will be written to the TRACE 1 screen. 

The following entry 

{ 

# include <trace_buf,h> 
extern struct trace _buf lljrbuf; 

) 

LAYER: 1 

STATE: any 

CONDITIONS: KEYBOARD “ * 

ACTIONS: 

{ 

traces(&ll Jrbuf, “End of test.’’); 

} 
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produces the following output on the TRACE 1 trace screen: 

End of test. 

The following coding produces the same output: 

{ 

U Include <trace_buf.h> 
extern struct tracejbuf lljrbuf; 

) 

LAYER; f 

STATE: any 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: 

{ 

const char * strlng_ptr; 
string_ptr = “End of test. 
traces (All trbuf, string_ptr); 

) 

set_utracejkey_label 

Synopsis 

extern void set_ulrace ^fkey label (trace buffer, label Jtr); 
unsigned int trace_buffer; 
const char * label _ptr; 

D e scri ptio n 

Use the setutrace J'keyJabel routine to modify the labels which identify the 
seven user-trace buffers. The default labels are TRACE 1, TRACE 2, TRACE 3, 
TRACE 4, TRACE 5, TRACE 6, TRACE 7. These labels correspond to the user-trace 
buffer with the same number. There is no Protocol Spreadsheet softkey 
equivalent of this routine. 

Inputs 

The first parameter identifies the user-trace function key whose label is to be 
replaced. Integers from 1 through 7 are valid values. The buffer number must 
correspond to a user-trace buffer that is written to in the program. If it does 
not or if the specified value is out of the valid range, the label is not assigned to 
any softkey. 

The second parameter is a pointer to a null-terminated string, i.e., the label that 
should replace the current one for the specified trace buffer. The label string 
has a maximum length of seven characters. If it has fewer than seven 
characters, it is padded to the right with spaces. If it has more than seven 
characters, only the first seven are used. 
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Example 

In the following example, new labels are assigned to the softkeys for user-trace 
buffers 2 and 3. If you press the USER TR softkey in Run mode, the labels 
TRACE 1 and TRACE 2 should be replaced with FRAME and PACKET. 


{ 

# include <trace_buf.h> 
extern struct trace_buf I2_lrbuf; 
extern struct tracejbuf 13 trbuf; 

) 

LAYER: 1 

STATE: deflnejabels 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

setjtirace Jkey_labet(2, " FRAME"); 
set_utrace Jkey_label(3, “PACKET"); 

) 

NEXTSTATE: wrlteJo_buffers 
STATE: write_to_buffers 

CONDITIONS? KEYBOARD “2' 

ACTIONS: 

{ 

tracef(&l2_trbuf, “Frame Level Information"); 

> 

CONDITIONS: KEYBOARD “3" 

ACTIONS: 

{ 

tracef(<H3_trbuf, "Packet Level Information"); 

) 


64.5 Attributes 


Attributes are written to the Display Window and to the trace buffers in 32-bit words 
that include 8 bits of character data (the second-lowest byte) and 24 bits of 
attributes. The format of the 32-bit data word, given in Table 64-4, is the same for 
the Display Window and for the trace buffers, 

In display f routines, the %m conversion specifier writes input to window_color and 
window _modlfier variables. These variables are then copied into data words written to 
the Display Window by string pointers in this and subsequent display f routines. See 
Figure 64-1. 

In trace f routines, the %m conversion specifier writes input to the 
trace _buffer_header structure for a particular user-trace buffer. The header is then 
copied into each data word written to the particular user buffer by string pointers in 
this and subsequent trace f routines. See Figure 64-2. 
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(A) Applying Attributes As Data Is Buffered 

There are two ways an attribute may be assigned to a character in the Display 
Window. One way uses the %m conversion specifier to assign attributes to the 
window _color and window jnodifier variables. This program, for example, 
includes a display f routine that uses the %m conversion specifier to write 
underlined data to the Display Window: 

STATE; apply _attrlbute_to wtndow_color variable 
CONDITIONS: ENTE - R STATE 
ACTIONS: 

{ 

pos_cursor (1,0); 

display <f (“%mThis data is underlined in the Display Window.", OxOdOOOOOOL) ; 

} 

The chart in Table 64-4 shows the hex value 04000000L in the "input" column 
alongside the underline attribute. This means that when the value Ox04000000L 
is input to the conversion specifier %m, an underline attribute is applied to the 
current display/ string and any that follow until the attribute is turned off. The 
underline attribute actually is applied to the external window_color variable. See 
Table 64-2. The windowjcolor and window jnodifier variables lend their 
attributes to every character that is written in a format string to the Display 
Window. In Run mode if the user presses the softkey for DSP WND, he will see 
his underlined string. Subsequent characters or strings written to the Display 
Window also will be underlined. 

The same attribute could be applied to a string in any of the user-trace buffers, 
as follows: 

{ 

U include <lrace_buf.h> 
extern struct tracejbuf 11 trbuf; 

) 

STATE; apply_attrlbute_to_header 
CONDITIONS; ENTER_STATE 
ACTIONS: 

{ 

trace f (All trbuf, “%mThis data Is underlined.”, OxOdOOOOOOL) ; 

) 

Only the header for the TRACE 1 display is affected by this %m conversion. 

Only the TRACE 1 buffer is written to. When other trace buffers are 
subsequently written to, the strings will not receive underlining as a result of the 
attributes applied above to the TRACE 1 header. 
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displayf( "%m DA TA" , OxQSlSPOQQL); 
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Figure 64-1 When a display f routine Is called, the attributes assigned via the %m 
conversion specifier are stored in two extern variables, accessible to the user. Both 
color and enhance attributes are contained in window _color. The low byte in 
window_color Indicates the color; the high byte contains enhancements. In this 
example, the following attributes will be assigned to characters written to the 
Display Window: reverse-image enhancement, gieen-on-black color, and ASCII 
font. Before a character is written to the Display Window, it is combined in a long 
with Us attributes, as mapped in the figure. 
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tracef(&t1_trbuf, "%mDATA" , 0xQ81Q00g£L); 
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Figure 64-2 When a trace J routine is called, the attributes assigned via the %m 
conversion specifier are stored in three variables in the trace-buffer header of a 
designated buffer. In this example, lljtrbuf.hdr holds the following attributes: 
reverse-image enhancement, green-on -black color, and ASCII font. Before a 
character is written to the buffer, it is combined in a long with its attributes, as 
mapped in the figure. 
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(B) Applying Attributes to Buffered Data 

The Display Window is an array of 1,088 long Integers, each including one byte 
of character data and three bytes of attributes. The character data is generated 
by strings in display routines. The attributes for each character are derived from 
the current window_color and window ^modifier values at the time the character 
is written to the display-window buffer. 

Once the data word is written to the buffer as an element in the array, it can be 
accessed and written to— and therefore changed— the same as any other location 
in memory. In the example that follows, a string is written to the Display 
Window without underlining. Then, as a result of a keyboard input from the 
operator, the first 32-bit word in the string (containing the first character, the 
letter "T”) is given a new value that includes the underline attribute. 

< 

extern unsigned long dlsplay_wlndow_buffer[1088J; 
extern struct 
{ 

unsigned char mpm; 
unsigned char cpm; 

) 

disptay_wi n dow_in dex_buffer [ 1 7 ] ; 

) 

STATE: apply _attrlbute_dlrectly_to_dlsplay_wlndow 
CONDITIONS: ENTER_STATE 
ACTIONS: 

1 

pos_cursor(],0); 

display f ("This data is not underlined."); 

) 

CONDITIONS: KEYBOARD “ " 

ACTIONS: 

{ 

disptay_window_buffer[64j = ((display _wlndow_buffer[64 j & ~Ox04000000L) \ 
0x040000001); 

display _\/indo\v_indexJbuffer{l}. mpm ++; 

) 

Incrementing display _windo\v_index_buffer. mpm is necessary to alert the 
processor on the CPM card (containing the display-controller software) that the 
program has changed the contents of the Display Window. Refer to Table 64-3 
for an explanation of this structure. 

The bitwise anding and oring in the example are necessary if you want to change 
certain bits in the word without affecting others. Note that the value whose 
complement (-) is ande d with display_window_buffer element #64 is the "mask” 
for the underline attribute in Table 64-4; and the value to the right of the or 
operator (|) is the “input” value for the underline attribute. 
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Table 64-7 

Conversion Specifiers 


Specifier 


Argument type 


Conversion Type 


%b 

Integer-array pointer 

array of long Integers. 2nd byte of each 
long Is displayed as charaoter. 1st, 3rd, and 
4th bytes Interpreted as attributes. Array 
begins at pointer, ends at element containing 
null charaoter and Special Character bit = 1 . 

%l 

Integer 

signed decimal representing 15-blt value 

%o 

unsigned charaoter 

unsigned character 

%#c 

unsigned character 

newline character displayed as ‘r rather than 
acted on 

%d 

Integer 

signed decimal representing 15-blt value 

%ld 

Integer 

signed decimal representing 31 -bit value 

%H 

character-array pointer 

character array Indicated by argument 
appears as small hex characters. 
(Precision as to number of characters 
becomes length of the array, overriding 
usual null-termination of strings.) 

%m 

Integer 

long Integer not displayed or printed, but 
written to attribute header-variable for Display 
Window or for one of the trace buffers 

%o 

Integer 

unsigned octal representing 16-blt value 

%lo 

Integer 

unsigned octal representing 32-blt value 

%tfo 

Integer 

unsigned octal representing 16-blt value, 
preceded by 0 

%#lo 

Integer 

unsigned octal representing 32-blt value, 
preceded by 0 

%p 

Integer 

unsigned hexadecimal (lower-case letters) 
representing 32-blt value, with a minimum 5 
digits displayed and a colon between the 4 
right-hand digits and the 1-4 left-hand digits. 
Useful for displaying CPU segment number and 
offset. 

%s 

character-array pointer 

array of characters beginning at pointer and 
ending at null terminator or at array-length 
precision, whichever occurs first 

%#s 

character-array pointer 

newline character displayed as h- rather than 
acted on 

%u 

Integer 

unsigned decimal representing 16-blt value 

%lu 

Integer 

unsigned decimal representing 32-blt value 

%#v 

Integer 

hex characters (example: b f e s ) representing 
16-blt value 

%#lu 

Integer 

hex characters (example: b f e sVj ) 


representing 32— bit value 
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Table 64-7 (continued) 


Specifier 

Argument type 

Conversion Type 

%x 

Integer 

unsigned hexadecimal (lower-case letters) 
representing 16-blt value 

%lx 

Integer 

unsigned hexadecimal (lower-oaee lettere) 
representing 32— bit value 

%#x 

Integer 

unsigned hexadecimal (lower-case letters) 
representing 16-blt value, preceded by Ox 

%/tlx 

Integer 

unsigned hexadecimal (lower-case lettere) 
representing 32— bit value, preceded by Ox 

%X 

Integer 

unsigned hexadecimal (upper-case letters) 
representing 16-blt value 

%IX 

Integer 

unsigned hexadecimal (upper-case letters) 
representing 32-blt value 

%#x 

Integer 

unsigned hexadecimal (upper-case letters) 
representing 16-blt value, preceded by Ox 

%#IX 

Integer 

unsigned hexadecimal (upper-case letters) 
representing 32-blt value, preceded by Ox 

%\n 

non© 

displays an V 

%% 

none 

displays a % 


64.6 Protocol Trace Buffers 

There are two Protocol Trace buffers, one dedicated to Layer 2 and the other to 
Layer 3 data. Run-mode softkeys for accessing these traces— PROTOCL, L2TRACE, 
and L3TRACE— appear when personality packages are loaded in at Layers 2 and 3. 
The prompt line is not part of these buffers. 

The size of each Protocol Trace buffer is 65,536 bytes. Of this total, two bytes are 
dedicated to the buffer header and two bytes to the trailer. The usable size of a 
Protocol Trace buffer, therefore, is 65,532 bytes. When a buffer’s limit is reached, 
new characters written to the end of the buffer force out the same number of 
characters from the beginning of the buffer. In Freeze mode you may scroll through 
the buffer using the cursor keys. 

You cannot write directly to the Protocol Trace buffers. Monitor the position within 
the buffers, as well as the wrap count, using the variables and structures discussed 
below. 

(A) Variables 

The addresses of the variables in Table 64-8 identify the physical location of the 
beginning and end of each Protocol Trace buffer. The beginning position is at 
the first data byte in the buffer. The end is just after the last data byte. 
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Table 64-8 

Protocol Trace Buffer Variables 


Type 

Variable 

Value (hex/declmal) Meaning 

extern unsigned char 

I2pp_trbuff 

First data byte In the Layer 2 
Protocol Trace buffer. Address 
of this variable— segment 
number plus offset— will Indicate 
the physical location of the first 
data byte, two bytes from the 
beginning of the buffer. Line 
Setup configured for emulate or 
monitor mode. 

extern unsigned long 

I2pp_trbuff_end 

First byte In the two-byte trailer 
of the Layer 2 Protocol Trace 
buffer— l.e., after the last data 
byte. Address of this 
variable— segment number plus 
offset— will Indicate the physical 
location of the end of the data 
area, hexadecimal FFFE bytes 
from the beginning of the 
buffer. Line Setup configured 
for emulate or monitor mode. 

extern unsigned char 

I3pp_trbuff 

First data byte In the Layer 3 
Protocol Trace buffer. Address 
of this variable— segment 
number plus offset— will Indicate 
the physical location of the first 
data byte, two bytes from the 
beginning of the buffer. Line 
Setup configured for emulate or 
monitor mode. 

extern unsigned long 

I3pp_trbu(f_end 

First byte In the two-byte trailer 
of the Layer 3 Protocol Trace 
buffer— l.e., after the last data 
byte. Address of this 
variable— segment number plus 
offset— will Indicate the physical 
location of the end of the data 
area, hexadecimal FFFE bytes 
from the beginning of the 
buffer. Line Setup configured 
for emulate or monitor mode. 


( 


64-46 


JUL '90 





64 Display Window end Trace 


(6) Structures 

The structure variables in Table 64-9 contain the high and low bytes of a 
beginning and ending offset and wrap-count in the Layer 2 and Layer 3 
Protocol Trace buffers. Create a logical beginning (or ending) offset within a 
buffer by combining the two offset-variables relating to a beginning (or ending) 
position into a single, two-byte offset. Add the resulting offset to the address of 
I3_lrbuff to identify the physical address of a logical location. 

The example below uses ttdefine preprocessor directives for determining 
beginning and ending offsets in the Layer 3 Protocol Trace buffer. When 
get_l3pp_value_end is encountered in a program, for example, each of the two 
"end” offset-variables is cast into a long and, if necessary, shifted left to its 
appropriate position in an offset. Then the two variables are added together. 

ttdefine get_I3pp_value_begln 

(((unsigned long) (I3pp_trbuff_ctl. begln_off_hi) « 8) + 

( (unsigned long) (I3pp_trbuff_ctl. begin _off_lo) ) ) 


ttdefine get_l3pp_value_end 

(((unsigned long) (I3ppjrbuff_cll. end _off_hi) « 8) + 

((unsigned long) (l3ppjrbuff_ctl.end_offJo))) 

When the ending offset, in this example, is added to the address of I3_lrbuff, 
the result is the address of the logical end in the buffer: 

unsigned long end_address; 

end_address = &l3_trbuff + get_l3pp_value_end; 

You may also use the offsets and wrap counts to determine how much data is 
currently in the buffer. Include the wrap count in the high two bytes of a 
four-byte offset. Then subtract the beginning offset from the ending offset. 


ttdefine get_I3pp_value_begin 

(((unsigned long) (I3pp_lrbuff_ctl. begin_wrap_hi) « 24) + 
((unsigned long) (!3pp Jrbuff7tt. begin _wrapJo) « 16) + 
((unsigned long) (l3pp_trbuff_ctl.begin_off_hi) « 8) + 
((unsigned long) (l3ppJrbuff_ctl.begin_off_lo))) 

ttdefine getJ3pp_value_end 

(((unsigned long) (I3pp_trbuff_ctl.end_wrap_hi) « 24) + 
((unsigned long) (l3pp_trbuff_cil.end_wrap_lo) « 16) + 
((unsigned long) (l3pp_trbuff_cll.end_off_hi) « 8) + 
((unsigned long) (I3ppjrbuff_ctl. end_offJo ) ) ) 

unsigned long end, begin, count; 
end = get_l3pp_value_end; 
begin = gel_l3ppj>alue_begin; 
count = end - begin; 
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Table 64-9 

Protocol Trace Buffer Structures 


Type Variable Value (hex/decimal) Meaning 


Structure Name: lpp_trbuff_ctl 


Declared as type struct. The variables contained 
In this structure monitor logical location In a 
Protocol Trace buffer. Reference structure 
variables as follows: lppJrbuf/_Ctl.begln_ofl_hl. 


unsigned char begln_aff_hl 


unsigned char begln_off_lo 


unsigned char begln_wrap_hl 


unsigned char begln_wrap_lo 


unsigned char end_off_hl 


unsigned char end_off_lo 


unsigned char end_wrap_hl 


unsigned char end wrapjo 


0-1110-255 

0-III0-2S5 

O-tt/0-25 5 
0- II 10-255 

0-11/0-255 

O-tUO-255 

0-1110-255 

O-ft/O-255 


High byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical beginning In the buffer. Range of the 
two-byte offset Is 2 through hexadecimal FFFE. 

Low byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical beginning In the buffer. Range of the 
two-byte offset Is 2 through hexadecimal FFFE. 

High byte of a 2-byte count of the number of 
times a logical beginning has wrapped through 
the Protocol Trace buffer. 

Low byte of a 2-byte count of the number of 
times a logical beginning has wrapped through 
the Protocol Trace buffer. It will have a value of 
zero only once. Once the count reaches 
hexadecimal FFFF, It will wrap to one. 

High byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical end In the buffer. Range of the two-byte 
offset Is 2 through hexadecimal FFFE. 

Low byte of a 2-byte offset from the physical 
beginning of the Protocol Trace buffer to a 
logical end In the buffer. Range of the two-byte 
offset Is 2 through hexadecimal FFFE. 

High byte of a 2-byte count of the number of 
times a logical end has wrapped through the 
Protocol Trace buffer. 

Low byte of a 2-byte count of the number of 
times a logical end has wrapped through the 
Protocol Trace buffer. It will have a value of zero 
only once. Once the count reaches hexadecimal 
FFFF, It will wrap to one. 


Structure Name: I2pp trbuff Ctl An Instance of the lpp_trbuft_ctl structure, 

declared as type extern struct lppjrbu(t_ctl. 
The variables contained In this structure monitor 
logical location In the Layer 2 Protocol Trace 
buffer. Has the same structure as 
lpp_trbulf_ctl. Reference structure variables as 
follows : I2pp_trbuf/_ctl. begln_olf_h . 
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Table 64-9 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

Structure Name: 

I3pp_trbuff_ctl 

An instance of the lppjrbutt_ctl structure, 
declared as type extern struct lpp_trbu/t_ctl . 
The variables contained In this structure monitor 
logical location In the Layer 3 Protocol Trace 
buffer. Has the same structure as 
lpp_trbuff_ctl. Reference structure variables as 
follows : I3pp_trbuf/_ctl . begin oft _h . 


(C) Routines 

The setjtracejkeyjabel routine allows the programmer to modify the current 
softkey labels for the Layer 2 and 3 Protocol Traces. There is no Protocol 
Spreadsheet softkey equivalent of this routine. 


setjtrace_fkey_label 

Synopsis 

extern void setjtrace Jkey_label (layer, label _ptr); 
unsigned ini layer; 
const char * label _ptr; 


Description 

Use the setjtrace _fkey_label routine to modify the labels which identify the two 
Protocol Trace buffers. The default labels are L2TRACE and L3TRACE. These 
labels correspond to the Layer 2 and 3 Protocol Traces. 

Inputs 

The first parameter identifies the Protocol Trace function key whose label is to 
be replaced. Integers from 1 through 7 are valid values. The number must 
correspond to a layer package which is currently loaded into the INTERVIEW. 

If it does not or if the specified value is out of the valid range, the label is not 
assigned to any softkey. 

The second parameter is a pointer to a null-terminated string, i.e., the label that 
should replace the current one for the specified Protocol Trace. The label string 
has a maximum length of seven characters. If it has fewer than seven 
characters, it is padded to the right with spaces. If it has more than seven 
characters, only the first seven are used. 
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Example 

In the following example, the X.25 Layer 2 and Layer 3 protocol packages have 
been loaded via the Layer Setup screen. New labels are assigned to the softkeys 
for both Protocol Traces. If you press the PROTOCL softkey in Run mode, the 
labels L2TRACE and L3TRACE should be replaced with X25 FRM and X25 PKT. 

LAYER: 1 

STATE: deflnejabels 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set_llrace_fkty_label( 2, "X2S FRM"); 
setjtrace _Jkey_iabel(3, "X2 5 PKT"); 

} 
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65 Counters, Timers, and Accumulators 


65.1 Counters 

The translator declares the following structure for counters that are entered as softkey 
tokens on the Protocol Spreadsheet: 

struct counter_struct 

{ 

unsigned long current; 
unsigned long last; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short samplejcounl; 
unsigned long lotal_high; 
unsigned short total_iow_low; 
unsigned short totat_low_high; 
unsigned short out_of_range; 
unsigned short changed; 
unsigned long pres; 
unsigned long old; 

): 

struct counter _slruct counter_name={0,0,0,-0ul}; 

The first eight counter variables in the structure are used to calculate statistical values 
whenever the counter is sampled. See Table 65-1. Three of the 
variables— counter_name. current, counter jxame .prev , and count er_name .old— come 
into play each time the counter is incremented, decremented, or set to a particular 
value. 

Counters are internal program variables and counter interrupts are strictly 
program-generated signals, so the C programmer is free to ignore this structure and 
maintain counts and statistics in a different way. Please note, however, that the 
68010 CPU expects this counter structure when it polls the 80286 periodically for 
statistical values to display in columns on the tabular and graphic stats screens. 

(A) Current, Previous, and Old Values 

When a counter is incremented, decremented, or set to a specific value on the 
Protocol Spreadsheet, the program does not signal a counter _name_change 
interrupt automatically. First it verifies that the new value of the counter really 
is a change from the previous value. See Table 65-2. For this comparison, the 
program needs to maintain two variables, counter jxame. current and 
counter jiame .prev . 
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Table 65-1 
Counter Structures 


Type 

Variable 

Meaning 

Structure Name: 

counter_struct 

Structure of a counter. Declared as type struct. 
Declared automatically If a program counter Is 
used. Program counters assigned to struoture 
as follows: struct counter_struot counter_name. 
Reference a structure variable as follows: 
counter_name . current . 

unsigned long 

current 

This value of the counter Is acted on dlreotly by 
program actions. 

unsigned long 

last 

Last sampled value: displayed on the tabular 
statistics screen. 

unsigned long 

maximum 

Maximum value of all samples; displayed on the 
tabular statlstlos screen. 

unsigned long 

minimum 

Minimum value of all samples; displayed on the 
tabular statistics screen. Should be Initialized as 
-Oul. 

unsigned short 

8ample_count 

Number of samples. 

unsigned long 

total_hlgh 

High four bytes of an eight-byte counter total. 

unsigned short 

totaljowjow 

Low two bytes of an eight-byte counter total. 
This two-byte variable counts to 65,535. 

unsigned short 

total_low_hlgh 

Bytes 3 and 4 of an eight-byte oounter total. 

unsigned short 

out_of_range 

Number Is out of range, either Incremented 
beyond the range or decremented below 0; 
should not be factored Into averages. 

unsigned short 

changed 

For future use. 

unsigned long 

prev 

When converting a counter action to C, the 
translator compares prev with current to 
determine whether counter has changed. Then 
prev Is updated to current and 
counter_neme_change Is signaled. 

unsigned long 

old 

When converting a counter condition to C, the 
translator compares old with current to 
determine whether true condition is new 
(transitional) . After program loglo has examined 
counter, old Is updated to prev. 


Here, for example, is the C translation of the simple action COUNTER example 
SET 5. 

counter_example. current = 5; 

if (counter jexample.prev l- counter-example, current) 

{ 

counterexample, old = counter_example.prev; 
counter-example, prev = counterjexample. current; 
signal (counter_exampIe_change) ; 
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Table 65-2 
Counter Variables 

i 

’ 

Type 

Variable 

Meaning 

extern event 

counter_name_change 

True when the named counter Is 
Incremented, decremented, or 
set to new value. This event will 
not be triggered unless a 
spreadsheet condition names 
the counter. Line Setup 
configured for emulate or 
monitor mode. 


It is clear from the translation that the variable counterexample. prev is used to 
limit the number of counter ^example _change interrupts to those cases where the 
current value of the counter really has changed. 

What is counter _name. old used for? We will preface the answer by citing the 
behavior of the counter in the following spreadsheet example. 

STATE: threshold_condltlon 
CONDITIONS: KEYBOARD “ ’ 

ACTIONS: COUNTER spacebar INC 
CONDITIONS: COUNTER spacebar GE 7 
ACTIONS: ALARM 

Each time you press the space bar while this program is running, the counter will 
increment, but no matter how many times you press the space bar the alarm will 
only sound once. It will sound on the seventh keystroke, the first time the 
counter is greater than or equal to 7. If the program had a decrement or set 
action that lowered the counter to less than 7, the alarm would sound again 
when the counter reached the 7 threshold. 

The translator accomplishes this threshold condition by coding the waitfor clause 
as follows: 

counter_spacebar_change && (I (counler_spacebar.old >= 7)) &.& (counter _spacebar. current >= 7): 

Since counter jspacebar.prev was used (and then updated to “current”) in the if 
statement that sent the counter _spacebar_change interrupt, the “old” value is 
required in the waitfor condition to insure a "transitional” or “threshold” 
counter condition. 
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(B) Sampling a Counter 

Here is the translator’s version of a counter sample action: 

counter_name.last = counter jiame. current; 
if (counter_name. current > counter _name. maximum) 

{ 

counter name. maximum = counter_name. current; 

) 

if (counter jiame. current < counter name, minimum) 

{ 

counler_name. minimum = counter_name. current; 

) 

counter_name.sample_count++; 

{ 

unsigned long temp; 

temp = (counter _name. current & OxOOOOffff) + counter_name,tolal_low_low; 
counter_name.total_low_low = temp; 

temp = (counterjtame. current » 16) + counter_name.total_low_hlgh + (temp » 16); 
counter_name. total Jow_htgh = temp; 
counter name, total _high += temp » 16; 

) 

counter_name. current = 0; 

In order to establish an average value for all samples, a grand total for current 
values at the time of each sampling must be maintained. Since an ordinary 
INTERVIEW current counter is 32 bits, the counter that maintains the grand 
total of current counts must be larger (64 bits). There is ho data type this large 
in C, and so the “total" counter is distributed among three variables and the 
somewhat complicated coding involving the temp variable is required to add the 
current counter to this composite counter. 


(C) Updating the Statistics Screen 

The CPM polls the MPM continuously to see if data is available to be output to 
the printer or the plasma display. This data includes character data, trace data, 
prompts, and values to be posted to the statistics screens. 

In order to know where on the statistics screens the values for the particular 
counters (and timers and accumulators) should be placed, the 68010 CPU on 
the CPM needs some help from the program (that is, from the MPM). This 
help is in the form of a "stat message" that the translator (or the programmer) 
codes once at the beginning of the program. The stat message is a structure that 
the MPM sends to the CPM. See Table 65-3. The stat message says, in effect, 
“Here is the address of a counter structure. When you access this structure 
during the running of the program in order to pull out the current, last, 
maximum, minimum, total, and sample-count values, display those values on the 
row of the tabular stats screen where the user has typed spacebar ” (for 
example). 
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Table 65-3 

Counter, Timer, and Accumulator Structures 


Type 

Variable 

Value (hex/decimal) 

Meaning 

Structure Name: stat msp 


Structure of a stat message. A stat message Is 
sent once for each named counter, timer, or 
accumulator. Declared as type struot. Declared 
automatically If a softkey-entered COUNTER Is 
used as a condition, or If softkey-entered 
COUNTER, TIMER, or ACCUMUL action Is taken. 
Program stat messages assigned to structure as 
follows: struct stat_msg name. You must 
assign values to the elements of the structure. 
Reference a structure variable as follows: 
name. type. 

unsigned short 

op_type 

0a00/2560 

Register statistics objects from the MPM to the 
CPM. Other values and meanings for future use. 

unsigned short 

type 

0 

0100/256 

0200/512 

accumulator 

counter 

timer 

unsigned long 

obJect_name 


The MPM (80266) address of a counter, timer, 
or accumulator name, converted to CPM (68010) 
format. To get an objectjiame address, enter: 
name, objectname = 
get_68k_phy s_addr( " name_otcounter ’ ) ; 

unsigned long 

ob)ect_address 


The MPM (80286) address of a counter, timer, 
or accumulator structure, converted to CPM 
(68010) format. To get a struoture address for 
a counter, enter: name.obJect_address = 
get_68k_phys_addr(&counler_name_p/_counter); 


Here is a C program that causes the current value of a counter named “key" to 
increment on the tabular-statistics screen each time an ASCII-keyboard key is 
struck. 

{ 

struct 

{ 

unsigned short opjype; 
unsigned short type; 
unsigned long ob)ect_name; 
unsigned long object jaddress; 

} stat_msg; 

extern unsigned long get _68k _phys_addr(); 
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struct counter struct 

{ 

unsigned long current; 
unsigned long last; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short sample_count; 
unsigned long tota!_high; 
unsigned short tolal_low_low; 
unsigned short total_low_high; 
unsigned short out_of_range; 
unsigned short changed; 
unsigned long prev; 
unsigned long old; 

}; 

struct counter_slructure counter_key; 
extern fastjevent keyboardnew_key; 

) 

STATE: update_stat_screen 

{ 

stat_msg.op_type = 2560; 
stat_msg,lype = 256; 

stat_msg. object_name = get_68k _phys_addr(“key"); 
slatjnsg.objectjaddress - get_68k _phys_addr(&counter_key) ; 
send^stat_message(&stat_msg); 
waitjor 
{ 

keyboard new key; 

{ 

coun ter_k ey. curren t*f; 

) 

} 

} 


The variable statjnsg. object jxame is a pointer to the name of the counter that 
the user has entered on the protocol spreadsheet. The program gives this name 
to the CPM, and expects the CPM to locate the name among the names that 
the user has entered on the tabular or graphic statistics menu. The delivery to 
the CPM of a pointer to the stats-menu name and a pointer to the counter 
structure is the purpose of the stat message. The message allows the CPM to 
correlate a line on the statistics results screen with an actual program counter (or 
timer or accumulator). 
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NOTE TO C PROGRAMMERS: When the translator creates a 
counter variable it adds the prefix counler_ to the spreadsheet 
name, but the programmer who is working primarily in C and is 
not making use of spreadsheet counters can name the counter 
any way he wishes, with or without the prefix. Similarly, the 
string that is communicated to the CPM in stat_msg.objecl_name 
("key” in the example above) must agree with the name on the 
stats menu, but it need not bear any resemblance to the name of 
the counter structure. 


NOTE ALSO: In most of the examples in this manual, we have 
not bothered to declare routines since it is not necessary. In the 
absence of a declaration, the compiler assumes that the routine is 
external and that it returns an integer. In nearly all cases, this 
assumption works. get_68k _physjiddr() returns a long, however, 
and must be declared. 
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65.2 Timers 

The translator declares the following structure for timers that are entered as softkey 
tokens on the Protocol Spreadsheet: 

struct timer _struct 

{ 

unsigned long current; 
unsigned long last; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short somple_count; 
unsigned long total _high; 
unsigned short total JowJow; 
unsigned short total JowJxlgh; 
unsigned long start _tick_value; 
unsigned short running; 
unsigned short changed; 

}; 

There are no timer conditions in the software (since timeouts provide the 
time-triggering function), and therefore alt of the variables in the structure serve as 
data for the CPM when it updates the stats screens. See Table 65-4. A stat message 
must be sent so the CPM can correlate a line on the statistics results screen with the 
correct program timer. The stat message is documented in the previous section on 
counters. The timer stat message is different only in respect that the stat _msg. type 
element should be set to 512 instead of 256. 

Timer restart, continue, and stop actions are explained in this section. The clear 
action is simply a matter of changing the elements in the structure to zero (except for 
timer _name. minimum, which becomes the one’s complement of zero). 

(A) Time Ticks 

Time ticks are timed increments of either of two hardware counters in the 
INTERVIEW. The programmer can select which of the two timing mechanisms 
to use for a given timer. 

One tick-counter is on the FEB card and is used to time-stamp incoming data 
and EIA leads. The intervals between ticks is determined on the FEB Setup 
menu. Ticks can be enabled/disabled on the same menu. The current value of 
this counter is available in a variable called 11 _tick_count. See Table 65-5. The 
current value always reflects the number of ticks since the program entered Run 
mode. The number of ticks may or may not equate to the amount of time in 
Run mode, since ticks are also encoded in playback data and the playback rate 
is subject to “local conditions” such as playback speed and idle suppression. 

FEB time ticks are the most precise timing mechanism in that they have a 
resolution to 10 microseconds. They also represent the most durable method of 
timekeeping, since they preserve the original data timings even during playback. 
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Table 65-4 
Timer Structures 


Type 

Variable 

Value (hex/decimal) 

Meaning 

Structure Name: timer struct 


Structure of a timer. Declared as type struct. 
Declared automatically If a program timer Is 
used. Program timers assigned to structure as 
follows: struct tlmerstruot tlmer_name. 
Reference a structure variable as follows: 
tlmer_name . current . 

unsigned long 

current 


Current value of timer, not updated while timer Is 
running. Values are In microseconds rounded to 
tick-unit on FEB Setup screen. 

unsigned long 

last 


Value of last sample: displayed on the tabular 
statistics screen. 

unsigned long 

maximum 


Maximum value of all samples: displayed on the 
tabular statistics screen. 

unsigned long 

minimum 


Minimum value of all samples: displayed on the 
tabular statistics screen. Should be Initialized as 
-Oul. 

unsigned short 

sample_count 


Number of samples. 

unsigned long 

totaljilgh 


High four bytes of an eight-byte timer total. 

unsigned short 

totaljowjow 


Low two bytes of an eight-byte timer total. 

unsigned short 

total_low_hlgh 


Bytes 3 and 4 of an eight-byte timer total. 

unsigned long 

start_tlck_value 


Tick-count In microseconds when timer was 
started, restarted, or continued. For 
line-related conditions at Layer 1 . this value Is 
stored In 11 _tlck_count: for non-line conditions, 
use get_wall_tlme_286jlcks routine. 

unsigned short 

running 

0 

-0 

Stopped. This variable Is polled and a zero stops 
the timer from Incrementing and sets the current 
value to tlmer_name. current (understood as 
microseconds). 

Running. All 1‘s In this variable causes the timer 
to Increment, showing a value that equals 
(wall-time ticks - tlmer_name.start_tlck_value) + 
timer _name . current. 

unsigned short 

changed 

-0 

For future use. 
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Tabls 65*5 
Timer Variables 


Type 

Variable 

Meaning 

extern unsigned long 

l1_tl°k_count 

This variable counts ticks from 
the start of Run mode, 
Tlck=eeo, mseo, etc., 
depending on FEB setup. 
Subtract early value from later 
value to create a timer. 
ACTIONS: 

{ displayf (‘%td msecs ’, 

{11 jlckjsount - 

timer jTame.start_tlck_value ) ) ;} 
Add to start _of junjtme to 
determine more precise current 
time for time-stamping events. 
Line Setup configured for 
emulate or monitor mode. 

extern unsigned long 

start_of_run_date 

Date when Run mode entered. 
Byte 1 (low byte) Indicates day; 
byte 2 stores month: and bytes 
3 and 4 Indicates year. May be 
used to time-stamp events. 

See also start _of _rur> _tl me . 

Line Setup configured for 
emulate or monitor mode. 

extern unsigned long 

start_of_run_tlme 

Time when Run mode entered. 
Byte 1 (low byte) Indicates 
seconds; byte 2 stores minutes; 
and byte 3 Indicates hours. 

May be used to time-stamp 
events. See also 
star(_o(junjdate and 
11 Jlckjcount. f 
Line Setup configured for 
emulate or monitor mode. 


t 


In the example below, the displayf (or traced) routine uses timer variables to time-stamp good BCCs on the DCE 
side. (Similar programming could determine the current date.) The tick unit selected on the FEB Setup menu la 
seconds. Adjust the program as needed for other tick units. 

{ 

extern unsigned long start jsfjunjiate, starl_of_runJlime, tl_tick_count; 
unsigned short seconds, hours, minutes, tick_mins, tickjecs, tick_hours; 

# define SECS (run time) (unsigned short ) (runjime & Oxff) 
tt define MINS(runjime) ((unsigned short) (run time» 8) & Oxff) 

} 

STATE: time 

CONDITIONS: DCE GOOD_BCC 
ACTIONS: 

{ 

tick_secs = II_tick_counl % 60; 

tick_mins = (ll_tick_count t SECS(start_ofrunJime)) / 60; 
llckjiours = (tick_mins + MINS(start_of runjime) ) t 60; 
displayf ("Time: % , 2d: % . 2d: % . 2 d\n ", 

(unsigned short) (((start j>fjun_time » 16) <6 Oxff) + tick_hours)%24 , 

(MINS(startjfjunJime) + tlckjnins)%60, 

(SECS (start ofjunjime) + tickjecs) %60); 

) 
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The other tick-counter is on the MPM and is referred to as the wall-time clock. 
This clock ticks once per millisecond and drives the timers displayed on the 
statistics results screens— at least while they are incrementing. At the moment a 
timer stops incrementing, the programmer can reach in and replace the 
incremented value with a timer value based the FEB tick-counter instead. 

The current value of this wall-time tick-counter is available to the program via 
the get_wall_time_286_ticks routine. The current value always reflects both the 
number of ticks and the actual elapsed time (“wall time") since the program 
entered Run mode. 

(B) Running 

While it increments on the stats screen, a timer always is driven by wall-time 
ticks. To start a current timer incrementing, first you must have sent a stat 
message to correlate the timer structure with a timer line on the stats screen. At 
that point the simple statement timer jxame. running = -0 will start the timer. 

The value of the timer at any given time while it is running will be the MPM 
(wall-time) ticks minus the timer_name. start jickjtalue plus any 
timer jiame. current value. 

To stop a timer, change timer jxame .running to zero. The current column of 
the timer will immediately display the value of timer_name. current (zero, unless 
you have done something in your program to calculate the current value of the 
timer). The stats display will interpret timer jiame. current as a value in 
microseconds and convert it to the unit selected for that timer line. 

(C) Restart 

The translator has two different versions of the timer restart action, depending 
on what condition precipitated the action. The first version is used if the 
condition was data-related (or EIA-related) and time ticks are enabled on the 
FEB Setup menu. Here is this data-timer version: 

unsigned long temp ; 

converl_tlck_count (ll_tick_count, &temp); 
tlmer_name. current = 0; 
tlmer_name. start Jickjalue = temp; 
timer _name. running = -0; 

The convert Jick_count routine converts 11 _tick_count into microseconds and 
stores the result in temp. The value of temp is assigned immediately to 
timer_name. start Jick_value. When the 68010 sees that timer jiame. running 
equals the one’s complement of zero, it subtracts the start-tick value from the 
11-tick count and displays the difference in the current column of the timer line. 
Since the start-tick value was derived a moment before from the 1 1-tick count, 
the difference will be zero. The current column on the stats screen should begin 
a timer at zero following a restart. 
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A slightly different version of the program is used if the condition was 
nondata-related or if time ticks are disabled in the FEB. The 
convert Jick_count routine is not used and the following routine is used in its 
place: 

get_wall_tlme_286jicks (&temp) ; 

This routine returns the current value of the wall-time tick-counter, in 
milliseconds zero-padded to microseconds. It stores the value in temp and the 
program proceeds as above. 

(D) Continue 

The timer-continue action is very similar to the restart. There are just two 
differences. One, the action is enclosed in an if statement that verifies that 
timer jtame. running equals zero— that the tinier actually is stopped, in other 
words; and two, timer jxame. current is not set to zero, but retains the value it 
received the last time the timer stopped. 

(E) Stop 

Here is one of the two versions of a timer stop action: 

if (timer name, running 1= 0) 

{ 

unsigned long temp; 

convert_tlck_count (U_tick_count, <ktemp); 
timer_name. current += temp - timer _name. start _tick_yalue; 
timer_name. running = 0; 

) 

In this translation, the start-tick value is subtracted from the current tick count, 
and any pending current value (held over if the timer was continued) is added 
in. The result is a new timer _name .current value. This value is posted to the 
stats screen as soon as the 68010 sees timer _name. running = 0. 

The other version of the stop action uses get _walljlime ^286_ticks instead of 
convert _tick_count . 

(F) Sample Action 

The code that produces the sample action is identical to the code that sampled a 
counter. See Section 65.1(B). The timer _name. sample _count variable’s not 
equaling zero causes minimum, maximum, and average values to be displayed. 

65.3 Accumulators 

Shown below is the structure of an accumulator as the translator declares it (and 
as the 68010 accesses it tcs update the statistics screens). Also refer to 
Table 65-6. Note that there is no current value, since an accumulator neither 
counts nor times. There are no “previous” and “old” values, because in its 
spreadsheet implementation an accumulator never is tested in a Conditions 
block. 
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struct accumulator struct 

{ 

unsigned long last; 
unsigned long maximum; 
unsigned long minimum ; 
unsigned short sample_count; 
unsigned long total_hlgh; 
unsigned short total_low_low; 
unsigned short total_low_high; 
unsigned short changed; 

>; 

struct accumulatorjstruct accumulator_name={0,0,-0ul); 

Here is the translator's version of an accumulate action when the object of the 
accumulation (selected by the user) was the maximum sampled value of a 
counter named framechar. 

accumulator_name.last = accumulator _framechar. maximum; 
if (accumulator_name.last > accumulator jname. maximum) 

{ 

accumulator_name. maximum = accumulator name, last; i 

} 

If (accumulator jtame. last < accumulator jtame. minimum) 

{ 

accumulator_name. minimum = accumulator_name.last; 

) 


accumulator jtame. samplejcounH-*; 

i 

unsigned long temp; 

temp = (accumulator _name. last <5 OxOOOOffff) t accumulator _name. total JowJow; 
accumulator jtame. total_low_low - temp; 

temp = (accumulator_name.lasl » 16) + accumulator _name. total JowJtlgh + (temp » 16); 
accumulatorjtame. total_low_hlgh = temp; 
accumulator_name.total_high += temp » 16; 

) 

accumulatorjtame. changed = -0; 

A stat message must be sent so the CPM can correlate a line on the statistics 
results screen with the correct accumulator, The stat message is documented in 
the previous section on counters. The accumulator stat message is different only 
in respect that the staijnsg.type element should be set to 0 instead of 256. 

The accumulator jiame. sample _count variable's not equaling zero causes 
minimum, maximum, and average values to be displayed. 
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Table 65-6 

Accumulator Structures 


Type 

Variable 

Meaning 

Structure Name: 

accumulator_struct 

Structure of an accumulator. Declared as type 
struct. Declared automatically by program when 
the user softkey-enters an ACCUMULATE 
action. Specific accumulator assigned to 
structure as follows: struct accumulator_struct 
accumulator_name. Reference a structure 
variable as follows: accumulator_name.last. 

unsigned long 

last 

Value of last sample; displayed on the tabular 
statistics screen. 

unsigned long 

maximum 

Maximum value of all samples; displayed on the 
tabular statistics screen. 

unsigned long 

minimum 

Minimum value of all samples; displayed on the 
tabular statistics screen. Should be Initialized as 
-Oul. 

unsigned short 

samp!e_count 

Number of samples. 

unsigned long 

total_hlgh 

High four bytes of an eight-byte accumulator 
total. 

unsigned short 

total_low_low 

Low two bytes of an eight-byte accumulator 
total. 

unsigned short 

total_low_hlgh 

Bytes 3 and 4 of an eight-byte accumulator total. 

unsigned short 

changed 

For future use. 


65.4 Routines 

get_68k_phys_addr 

Synopsis 

extern unsigned long get_68k _phys_addr(variab!e _ptr); 
unsigned char * variable _ptr; 

Description 

This routine converts the address of a specified variable in the 80286 processors 
(MPM boards) to 68010 (CPM) format. This routine must be declared. 


Inputs 

The only parameter is the address to be converted. 
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feHHPS 

The get_68k _phys_addr routine returns the converted address. 

Example 

See send_stat_message routine. 

send_stat_message 

Synopsis 

extern void send_stat_message(struct_stat_msg_ptr); 
struct $tat_msg 

{ 

unsigned short op_type; 
unsigned short type; 
unsigned long object_name; 
unsigned long object _address; 

); 

struct stat_msg * struct _stat_msg_ptr; 

Description 

The send_slatjnessage routine sends the stat message structure to the 68010 
CPU (CPM board). The current use of this routine sends the addresses of 
program counters, timers, and accumulators in the 80286 processors (MPM 
boards) to the CPM board where the tabular and graphic statistics displays are 
located. 

The routine is called only one time in a program for each named counter, timer, 
or accumulator. Entering COUNTER as a condition or action (or TIMER or 
ACCUMUL as actions) via softkey on the Protocol Spreadsheet automatically 
declares the counter named and sends the stat message. 

Inputs 

The only parameter is a pointer to the structure of the stat message. For an 
explanation of the elements of the stat message, see Table 65-3. 

Ex a m ple 

You plan on incrementing a counter named "dtejnfo" when a DTE Info frame 
is detected. 

{ 

struct 

{ 

unsigned short opjype; 
unsigned short type; 
unsigned long objectjtame ; 
unsigned long object _address; 

} $tat_msg; 
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struct counter structure 

{ 

unsigned long current; 
unsigned long last; 
unsigned long maximum; 
unsigned long minimum; 
unsigned short sample_count; 
unsigned long totalhigh; 
unsigned short tolal_low_low; 
unsigned short total Jow_high; 
unsigned short oul_of_range; 
unsigned short changed; 
unsigned long prev; 
unsigned long old; 

): 

Struct counlerjstructure counter _dte_in/o = {0, 0, 0, - Out }; 
extern unsigned long get 68k _phys_addr(); 

} 

LAYER: 2 

STATE:send_statjnessage 
CONDITIONS: ENTER STATE 
ACTIONS: “ ’ 

{ 

stat^msg. op_type = 2560; 
stat_msg. type - 256; 

stat^msg. object _name - getj&8k _j>hys_addr(" dte_info” ) ; 
stat_msg. object _address = get_68k _phys_addr(&counter_dte_info); 
send_slat message (dstat msg); 

) 

NEXT^STATE: count Jnfo 
STATE: countjnfo 

CONDITIONS: DTE INFO 
ACTIONS: 

{ 

counter_dte_info. currents +; 

) 


get_wall_time_ticks 

Synopsis 

extern void get _walljtme_ticks (ticks _68k Jormat __ptr); 
unsigned long * ticks_68k_format _ptr; 

Description 

The getjvalljimejicks routine gets the number of wall-time ticks (in CPM 
storage format) from the time H was hit. The wail clock gives millisecond 
resolution rounded to microseconds. 

Inputs 

The only input is a pointer to the location where the returned time-tick value 
will be stored. 
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Example 

{ 

unsigned long ticks; 

} 

LAYER: 2 

STATE: get_tlcks 

CONDITIONS: KEYBOARD “ * 
ACTIONS: 

{ 

get_wall_time tlcks(&tlcks); 

) 


get_walMlme_286_ticks 

Synopsis 

extern void get_walljlme_286_ticks(ticks~286 Jormat _ptr }; 
unsigned long * ticks_286_Jormal _ptr; 

Description 

The get_wail_iime_286jicks routine gets the number of wall-time licks (in 

MPM storage format) from the time @ was hit. The wall clock gives millisecond 

readings rounded to microseconds. Use this routine prior to setting the 

start Jick_value in a timer action when Time Ticks: |$j|§ has been selected on 

the Front-End Buffer Setup screen. Also use this routine to derive the 

start _tick_value if the condition is not line-related, e.g., KEYBOARD, even when 

time ticks are enabled on the FEB Setup menu. 

Inputs 

The only input is a pointer to the location where the returned time-tick value 
will be stored. 


Example 

< 

unsigned long ticks_286; 

) 

LAYER: 3 

STATE: get_tlcks 

CONDITIONS: KEYBOARD “ " 
ACTIONS: 

< 

get_wa ll_t imeJ286jicks(& licks_2 86); 
displayf ("%lu", llcks_286); 

) 
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convert_tick_count 

Synopsis 

extern void convert _tick_count(mpm JormatJicks, converted Jicks _ptr); 
unsigned long mpm _format Jicks; 
unsigned long * converted jicks _ptr; 


Description 

The convert Jick_count routine converts a. designated tick count into 
microseconds. 

Use this routine to derive the start _tick_va!ue for a timer action if ticks are 
enabled on the FEB Setup menu and the condition is line-related, e.g., RCV 
INFO. 

Inputs 

The first parameter is a designated tick count as long as it is in MPM storage 
format. It may be any of the layer tick counts. The unit of the 11 jick_count 
(and other layers’ tick counts) value is determined on the Front End Buffer 
menu. 

The second parameter is a pointer to the location where the returned tick count 
converted to microseconds will be stored. 

Example 

1 

extern unsigned long UJick_count ; 
unsigned long converted Jicks; 

) 

LAYER: 1 

STATE: convert_tlcks 

CONDITIONS” RECEIVE GOOD_BCC 
ACTIONS: 

1 

convert jick_count (II jick_count, ^converted Jicks); 
display f (“ %lu" , converted jicks); 

) 
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PDU 



Figure 66-1 Primitive Data Unit and sample Pointer-List Buffer being passed down 
the layers. 
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The most convenient tools for handling protocol headers while data is moving down and up 
the layers in the INTERVIEW are the spreadsheet SEND and give daTA actions in the various 
protocol packages. For instances when a protocol package is not loaded, such as when you 
are developing a new protocol or simply using a protocol that is not yet an option on the 
Layer Setup screen, OSI structures, variables, and routines in C become essential tools also. 

66.1 Structures 

The programmer may access the information in primitive data units conveniently by 
using a C structure as a multibyte pointer that is superimposed on data in the PDU’s. 
Before using a structure-pointer, it is necessary to understand the contents of IL 
buffers and primitive data units. All structures referenced may be found in 
Table 66-1. 

(A) Interlayer Message Buffers 

1. Configuring (he numberlsize of IL buffers. By default, there are a maximum 
sixteen IL buffers in use at a given time. Each buffer’s size is 4,096 bytes. 
You may change the number and size of the interlayer (IL) buffers. The IL 
BUFS softkey on the Protocol Spreadsheet presents seven number/size 
combinations that allocate 64 Kbytes of RAM to IL buffers. See Section 27. 
In addition to these softkey selections, there are two C preprocessor 
directives the programmer may use to reconfigure the number and/or size of 
IL buffers: 

(a) ttpragma iijbuffers sets the number of IL buffers that will be available 
at a given time. Following the directive, enter a space and then a 
decimal integer within the range 4 through 255. In the following 
example, the number of buffers is set to 25: 

((pragma il_buffers 25 

The specified number of buffers will override the number selection on 
the Interlayer Buffers menu. The buffer size indicated on the Interlayer 
Buffers menu will remain unchanged, however, unless altered via the 
ttpragma il_buffer_size directive. 
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(b) ti pragma il_buffer_size sets the size of IL buffers. Following the 

directive, enter a space and then a decimal integer within the range 33 
through 65535. These values include the 32-byte buffer header. (See 
Section 2. below.) In the following example, the size of buffers is set 
to 8 Kbytes: 

tt pragma iljbufferjsize 8192 

The specified buffer size will override the size selection on the 
Interlayer Buffers menu. The number of buffers indicated on the 
Interlayer Buffers menu will remain unchanged, however, unless altered 
via the ffpragma il_buffers directive. 

Be careful when you are passing messages down from higher layers that 
you do not make the buffer size too small. Even small messages require 
a buffer large enough to accommodate the overhead of linked lists. 

These two directives provide the programmer with more flexibility in 
configuring IL buffers than the Protocol Spreadsheet softkeys. With the 
#pragmas, the available RAM for IL buffers may exceed the 64-Kbyte 
threshold of the IL BUFS selections. 

The memory required for IL buffers is the product of the number and size 
of the buffers (number * size). If this amount exceeds available memory, ( 

your program will not compile and the message “Error 219: Out of memory 
during compilation — program too big” will be displayed. Available memory 
for IL buffers varies depending on the complexity of your program. 

2. IL buffer components . IL buffers may be one of two kinds: data-character 
or pointer-list. In buffers being passed up the layers, data-character buffers 
(Figure 66-2) are always used. In buffers going down the layers, pointer-list 
buffers (Figure 66-1) are primarily used. The difference is that pointer-list 
buffers contain list-nodes which provide information about the location of 
data (or ‘'lists") inserted or referenced in the buffer, while data-character 
buffers do not. 

(a) Header, Each IL buffer contains a header that stores useful information 
such as the status of the maintain bits that prevent the buffer from being 
returned to the general pool; the position of the buffered data in the 
INTERVIEW’S display buffer; and the tick count (time) when the data 
was buffered from the line. (See il_b uffer structure.) 

(b) Service Data Unit. The IL buffer also contains the data itself. This data 
component, the service data unit (or “SDU”), is added to as the buffer is 
passed down the layers, and subtracted from as a buffer travels up the 
layers. A data-character IL buffer includes all the data that was present 
when the data was first buffered, and the contents of this buffer do not 
change as the buffer is passed up the layers. What changes is the service ^ 
data unit, derived from the data-start offset in the PDU. 
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The first part of the SDU in a pointer-list buffer is a list-header node 
(structure il_Iist_header) which contains information about the location 
of the first and last text nodes. As a buffer is passed down from Layer 
3 to Layer 2 in X.25 (see Figure 66-1), a new text node containing a 
Layer 3 protocol header is inserted in buffer. Since the Layer 3 data 
will precede user data, the list node for the protocol information is 
referenced ahead of any other list nodes, changing the first-node 
reference in the list header. (If text is appended to the end of existing 
data, the list node referenced as last will change.) 

The SDU in a pointer-list buffer also includes list nodes (structure 
UJistjiode) which give a pointer to data, the length of the data pointed 
to, and the offset from the start of the buffer to the next list node. 

Finally, the service data unit in all buffers includes data, whether copied 
into the buffer (usually protocol information) or located in memory 
outside of the buffer (usually user data). 

PDU 



Figure 66-1 Primitive Data Unit and sample Dala-Characier Buffer being passed up 
the layers. 
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(B) Primitive Data Units 

Like interlayer message buffers, PDU’s have a format that is dependent on 
which direction the primitive is being passed. Refer again to Figure 66-1 and 
Figure 66-2. 

1 . IL buffer number. The buffer number to be passed with the primitive is 
always stored in the primitive. This buffer number is actually an 
80286-processor segment number. 

2. Data-start offset. The offset from the beginning of the buffer to the 
beginning of the service data unit for a given layer is different for the two 
types of buffers. In a pointer-list buffer going down the layers, the 
data-start offset will indicate the offset from the beginning of the buffer to 
the list-header node. This offset will vary if different linked lists have been 
started at different layers. Each list will have its own list header. In a 
data-character buffer going up the layers, the data-start offset will change 
from layer to layer. For example, a buffer containing X.25 data that is 
being passed from Layer 2 to Layer 3 will have an offset at Layer 3 two 
bytes beyond the offset at Layer 2. 

3. Data length. The size of the SDU in a data-character buffer also varies 
from layer to layer. In the example just given, the SDU will be smaller by 
two bytes at Layer 3 than it was at Layer 2. In pointer-list buffers, the 
length of all data is unknown at any given layer. 

(C) Accessing Information In Structures 

There are two stages that are preliminary to accessing the information in these 
structures. The first step is to convert the 80286-processor segment number into 
a 32-bit address. The second stage is to place a pointer, in the shape of an IL 
buffer structure, at that address. Let’s use an IL buffer as an example. 

1. Converting a segment number. The IL-buffer segment number is returned 
any time you access one of the external, protocol-independent il_buffer 
variables listed in Table 66-1. These variables have names like 
m_lo_dlJl_buff and up_njl_buff. 

To make a pointer to an IL buffer, (1) shift the 80286 segment number to 
the left sixteen bits, since a full address in the 80286 is 32 bits long; (2) cast 
it as a long, so that the segment number is in the high 16 bits and the offset 
to a buffer for that segment is zero (the low 16 bits); and (3) cast it as a 
pointer. The following expression will take care of all three requirements: 

(void *) ((long) m_lo_dt_U_buff «16); 

Now you have a pointer to the first memory location of the most recent 
monitor-mode IL buffer passed up from Layer 2 to Layer 3. An 
upward-moving IL buffer was illustrated in Figure 66-2. The precise 
structure of both the IL buffer is given in the following declaration. 
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{ 

struct il _buffer 

{ 

unsigned short lock; 
unsigned short maintaln_bits; 
unsigned short buffer jsize; 
unsigned short transmit Jag; 
unsigned short receive Jag; 
unsigned long charjbuff Jramejtart; 
unsigned long charjbuff Jrame_end; 
unsigned short tlckjountjtigh; 
unsigned short tlckjountjnid; 
unsigned short tickjountjow; 
unsigned short available jpace _offset; 
unsigned short bytes jemainlng; 
unsigned long bccjndicator; 
unsigned char data (406-11; 

)l 

) 

2. Create a structure-pointer at a given address. First, declare the structure of 
UJbuffer, as indicated above. Then declare il_buffer j pointer as a 
structure-pointer, as follows: 

struct it _buffer * iljsuffer _ pointer ; 

Converting the segment number and assigning it to ilj?uffer _ pointer may be 
accomplished with this one statement: 

lljbuffer join ter = (void *) ( (long) mJo_dlJl_buff «16); 

Now a structure has been created around the most recent upward-moving IL 
buffer at Layer 3. This means that rather than moving a pointer around in 
the IL buffer, you can access elements in the buffer directly. The 
tick_count_low variable, for example, would be called 

il _buffer _pointer->tick_count Jow . (The -> operator is used in place of the 
dot operator in structure-pointers.) 

The first element of the data string would be called 

iljjuffer _pointer->data(0] . Here is a program that displays on the prompt 
line the fifth data element, the packet-type byte, in every IL buffer that is 
monitored at Layer 3. 


JUL '90 


66-7 




INTERVIEW 7000 Series Advanced Programming ; ATLC-1 07-951 -108 


{ 

extern event m_to_dl jrmtv; 
extern volatile unsigned short m_lo_dl_ll_buff; 
struct iljruffer 
{ 

unsigned short lock; 
unsigned short maintain_bits; 
unsigned short bufferjsize; 
unsigned short transmil_tag; 
unsigned short receivejtag; 
unsigned long char_buff_framejttart; 
unsigned long char_buff_frame_end; 
unsigned short ticfcjount_high; 
unsigned short lick_count_mid; 
unsigned short tickjountjow; 
unsigned short available_spacejffset; 
unsigned short bytes _remaining; 
unsigned long bccjndtcator; 
unsigned char data 14064}; 

}; 

struct II buffer * il buffer jointer; 

) 

LAYER: 3 

STATE: monltorjl buffers 
CONDITIONS: 

{ 

m lo_dl _prmtv 

} 

ACTIONS: 

{ 

UJbuffer jointer - (void ’) ((long) m_to_dl_il_buff «I6); 
pos_cursor (0,0); 

displayf ("%02x ", il_buffer jointer->dataf4]); 

} 

If you run this program, be sure to load in the Layer 2 and Layer 3 
personality packages for X.25. These packages will take care of delivery of 
the monitor primitives to Layer 3. 
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Table 66-1 
OSI Structures 


Type 

Variable 

Value (hex/decimal) 

Meaning 


St ru ctur e Name ; pdu 


unsigned char prlmlt1ve_oode 


unsigned char path 0-8 

unsigned long parameter 

unsigned short relay_baton 

unsigned short ll_buffer_nunnber 

unsigned char buffer_contents 0 

1 

unsigned short data_start_offset 


unsigned short datajength 


Structure of an OSI primitive data unit (PDU). 
Declared as type struct. Use this structure as follows. 
Declare the entire structure. Make a pointer tc a PDU 
by shifting m_lo_cf/_pdu_seg (or up_n_pdu_seg) 16 bits 
to. the left. Then convert this pointer to a pointer to a 
PDU structure: struct pdu * pdu_polnter 
pdu_polnter =( void *)((long)m_lo_dl_pdu_seg « 16). 
Reference a 9tructure-polnter variable as _ follows: 
pdu_poln!er->primltlve_code . 

Codes tor OSI variables are listed in Table 66-2 
through Table 66-6. For Layer 3 primitive codes, 
for example, refer to Table 66-4. The value of this 
variable Is also stored In external variable 
m_lo_d/_prmtv_code (or up_n_prmtv_code) . 

Path number, both directions. The value of this 
variable Is also stored In external variable 
m_lo_d/_prmtv_path (or up_n_prmtv_path) . 

For future use. At present, under user control. 

Maintain bit passed with an Interlayer-message 
buffer, both directions. Zero In this variable 
Identifies maintain bit. 

Segment number of the Interlayer-message 
buffer, both directions. The value of this variable 
Is also stored In external variable m_Io_d/_ll_buff 
(or up_n_ll_buff) . 

Contains data-character buffer type, Must be 
used for buffer being passed up. 

Contains pointer-list buffer type. May be used 
for buffers being passed up, but Is currently used 
primarily for buffers being passed down. 

Offset from the beginning of the buffer to the 
header node In the SDU of an Interlayer-message 
buffer In an OSI primitive being sent down from a 
layer above. In a primitive being sent up from a 
layer below, It Is the offset to the SDU. Varies 
according to the layer at which the buffer Is 
located. For example, In a buffer passed up to 
Layer 3 from Layer 2, the offset would be to the 
beginning of the Layer 3 header, bypassing Layer 
2 header Information. The value of this variable 
Is also stored In external variable 
mJo_dl_$<iu_o((set (or up_n_sdu). 

Length of the service data unit. Including headers 
and user data. Only for primitives sent up from 
layer below. Varies with the layer where the 
buffer Is located. For example, at Layer 3, 
length would exclude Layer 2 header (or trailer) 
Information. The value of this variable Is also 
stored In external variable mJo_d/_sdu_slze , 
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Table 66-1 (continued) 


Type Variable Value (hex/decimal) 


Meaning 


Structure Name: il_buffer 


unsigned short lock 

unsigned short malntaln_blts 

unsigned short buffer_slze 


unsigned short transmlt_tag 


unsigned short recelve_tag 


Structure of an Interlayer-message buffer, both 
directions. Declared as type struct. Use this 
structure as follows. Declare the entire structure. 
Make a pointer to an ll_buffer by shifting 
mJo_d/JI_buff (or up_n_ll_buff) 16 bits to the left: 
ll_buffer _pclnter = (void *) ((long|(lo_dlJI_buff « 16). 
Then convert this pointer to a pointer to an ll_buffer 
structure: struct ll_buffer ‘ l!_bufferj)olnter. 
Reference a structure-pointer variable as follows: 
ll_buffer_polnter->tlck_count_low. 

0 Internal variable which prevents structure from 

being updated by more than one program at the 
same time. 

Two-byte variable which provides the status of 
the maintain bits. A bit with a value of 1 Is In 
use. 

1000/4096 default value 

21 -lilt 133-65535 Specific value depends on buffer size set via 
IL_BUFFERS programming block or #pragma 
ll_buffer_slze 

Bits 1-3 define boc Indication : 

0 no bcc 

1 good bcc 

2 bad bcc 

3 abort 

4 half bad bcc (DDCMP) 

Bits 4-0 for future use. 

Bits 1-3 define bcc Indication : 

0 no bcc 

1 good bcc 

2 bad bcc 

3 abort 

4 half bad bcc (DDCMP) 

Bit 4 Identifies side of the line : 

0 td 

1 rd 

Bit 5— message buffer overflow : 

0 frame fits In buffer 

1 frame too large for the buffer 


unsigned long 
unsigned long 


Bits 6-8 for future use. 

char_buff_frame_start Location In the character buffer of the start of 

the buffered data. 

char_buff frame_end Location In the character buffer of the end of the 

buffered data. 

(Il_bulfer structure continued on next page) 
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Table 66-1 (continued) 


Type 

Variable 

Value (hex/decimal) 

Meaning 


il_buffer (continued) 


unsigned short 

t!ck_count_hlgh 

Value of Internal variable that counts the number 
of times H_tlck_count has reached Its maximum 
value. Together, the three ll_bufler tick-count 
variables preserve at each layer the original time 
when the end of the data (BCC) was clocked Into 
the buffer. 

unsigned short 

tlck_count_mld 

16 high-order bits of 32-blt H_tlck_count. 

unsigned short 

tlck_count_low 

16 low-order bits of 32-blt lljlckcount. 

unsigned short 

avallab1e_space_offset 

Offset to the next available space In the 
Interlayer-message buffer. 

unsigned short 

bytes_remalnlng 

Available number of bytes remaining in the buffer. 

unsigned long 

bccjndicator 0 

reserved 

unsigned char 

data [4064] 

Contains all data Including each layer's header 
Information, as well as the first of two block 
check characters. Does not vary from layer to 
layer. Default size Is 4064, but may range from 
33-66535 (hex 21-ffff) depending on the buffer 
size set via IL_BUFFERS programming block or 
^pragma ll_bu(fer_size. 


Structure Name: il_list_header Structure of the header node In an 

Interlayer-message buffer. Only for primitives 
sent down from the layer above. Declared as 
type struct. Use this structure as follows. 

Declare the entire structure. Make a pointer to 
an lljlst header by shifting up_njl_buff (or 
m_lo_d/_ll_buff ) 16 bits to the left and adding the 
data_start_offset from the PDU structure (also 
stored as external variable up_n_sdu or 
m_lo_d/_sdu_offsef) : 
li_llst_header_polnter = 

(void *)((|!ong)up_n_ll_buff) « 16) + up_n_sdu) . 
Then convert this pointer Into a pointer to an 
IIJIst_header structure : 
sTruct lljlst_header * ll_llst_header_polnter. 
Reference a structure-pointer variable as follows: 
IIJist_header_polnter->last_ n ode_offset. 

unsigned short flrst_node_offset Offset from the beginning of the buffer to the 

first text node In the buffer. Varies according to 
the layer at which the buffer is located. At Layer 
2. the offset would be to different starting node 
than at Layer 3. 

unsigned short last node offset Offset to the location of the last text node In the 

buffer, from the beginning of the buffer, 

unsigned long reserved reserved 
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Table 66-1 (continued) 


Type Variable Value (hex/decimal) 


Meaning 


Structure Name: il fist node Structure of text nodes In an Interlayer-message 

buffer. Only for primitives sent down from the 
layer above. Declared as type struct. Use this 
structure as follows. Declare the entire 
structure. Make a pointer to an IIJIst_node by 
shifting up_n_ll_buff (or /r>Jo_d/JI_buff) 16 bits to 
the left and adding the flret_node_offset (or 
last_node_offset) from the lljlstjieader 
structure: ll_llst_node_polnter = 

(void ‘)<((long)upji_IIJ>uff « 16) + 
IIJIst_header_polnter->flrst_node_offset) . Point 
to the next node as follows: 
nextjiode _polnter = (lljlstjiodepolnter + 
ll_llst_node_polnter->next_node_of(set) . 


unsigned char ‘ data_polnter 

unsigned short datajength 


Pointer to the data In a text node. 
Length of the data In a text node. 


unsigned short next_node_offset Offset to the location of the next text node In the 

buffer, from the beginning of the buffer. 

Generally, there Is a text node for each layer's 
header Information and one for the user data. A 
buffer that started at Layer 3 would have two 
text nodes, one for Layer 3 header Information 
and one for user data (If any). At Layer 2, the 
buffer would acquire an additional text node. 
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66.2 Variables 


OSl variables are layer-specific. The information stored in the OSI variables may be 
obtained by using the structure-pointer to IL buffers and primitives. But rather than 
requiring the user to repeat this process at each layer as a buffer moves through the 
layers, monitor and emulate variables have been made available at Layers 2-7 to 
store layer-specific, as well as general, information: the interlayer-buffer number, 
the offset to the service data unit, the path number, the size of the SDU, the 
segment number of the PDU, etc. There are also event variables which indicate that 
a primitive has. been received. at a given layer. Table 66-2 through Table 66-8 give 
the current OSI variables and their meanings. 

The exchange of connect primitives shown primarily in Figure 33-4 is demonstrated in 
Figure 66-3 using C variables and routines. The SEND actions insert data in a buffer 
and send the buffer in a DATA REQ primitive. See Section 66.3 for an explanation of 
the Jnsert Jl _buff_list _cnt and send primitive routines. The conditions use event 
variables to detect primitives and non-event variables to identify specific primitive 
types. 


LAYER 3: 


/ {send dl prmtv below 

ENTER STATE / buffer number, relay baton. 

/ data start offset, 0, 


{!o dl prmtv && / 

(to dl prmtv code ==; 0x43)} / SEND RESTART 

/ (5x40, path):) 


__z 


__J DL DATA | „ 

N REQ 

V 




LAYER 2: 


eto. 


{up dl prmtv && / 


/ {send dl prmtv above 

, /(II buffer number, relay baton, 



RCV UA / data start offset, size, 


/ "0x43, path);} 



Figure 66-3 Layer 3 uses conned primitives to be sure lhal the Layer 2 entity below has 
established a link. 
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Table 66-2 

Layer 1 OSI Variables 


Type 


Variable Value (hex/decimal) Meaning 


extern volatile unsigned char 


ph_prmtv_type 


20/32 

ph activate req 

21/33 

ph activate Ind 

22/34 

ph activate reap 

23/35 

ph activate conf 

24/36 

ph data req 

25/37 

ph data Ind 

2a/42 

ph reset req 

2b/43 

ph reset Ind 

20/44 

ph reset resp 

2d/45 

ph reset conf 

2e/46 

ph deactivate req 

2f/47 

ph deactivate Ind 

30/48 

ph debug req 

31/49 

ph debug Ind 

33/51 

ph error report Ind 

34/52 

ph xmlt req 

35/53 

ph set Idle req 

38/56 

ph mgt facility req 

39/57 

ph mgt facility Ind 


OSI primitive code for primitives 
moving between Layers 1 and 2. 
Line Setup oonflgured for 
emulate mode only. 


I 


66-14 


JUL ’90 





66 OSI 



Table 66-3 

Layer 2 OSI Variables 


Type 

Variable Value (hex/decimal) 

Meaning 


extern event 


lo_ph_prmtv 


extern event 


m_l°_ph_prmtv 


extern event 


up_dl_p rm tv 


extern volatile unsigned short lo_ph_pdu_eeg 


extern volatile unsigned short m_lo_ph_pdu_seg 


extern volatile const unsigned char lo_ph_prmtv_code 


extern volatile const unsigned char m_lo_ph_prmtv_code 


True when an OSI primitive Is 
received at Layer 2 from Layer 
1 . Line Setup configured for 
emulate mode only. 

True when an OSI primitive Is 
received at Layer 2 from Layer 
1 . Line Setup configured for 
emulate or monitor mode. 

True when an OSI primitive Ib 
received at Layer 2 from Layer 
3. Line Setup configured for 
emulate mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 2 from Layer 
1. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 2 from Layer 
1 . This segment number oan 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


21/33 

ph activate Ind 

23/35 

ph activate conf 

25/37 

ph data Ind 

2b/43 

ph reset Ind 

2d/45 

ph reset conf 

2f/47 

ph deactivate Ind 

31/49 

ph debug Ind 

33/51 

ph error report Ind 

39/57 

ph mgt facility Ind 


OSI primitive code received at 
Layer 2 In a PDU from Layer 1 
Line Setup configured for 
emulate mode only. 

24/36 

td ph data Ind 

25/37 

rd ph data Ind 


OSI primitive code received at 
Layer 2 In a PDU from Layer 1 . 
Line Setup configured for 
emulate or monitor mode. 
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Table 66-3 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


extern volatile con6t unsigned char 

lo_ph_prmtv_path 

0-8 

Path number received at Layer 
2 In a PDU from Layer 1 . Line 
Setup configured for emulate 
mode only. 

extern volatile const unsigned char 

m_lo_ph_prmtv_path 

0-8 

Path number received at Layer 
2 In a PDU from Layer 1 . Line 
Setup configured for emulate or 
monitor mode. 

extern volatile unsigned short 

lo_ph_ll_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 2 In a PDU 
from Layer 1 . This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

mJo_phJI_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 2 In a PDU 
from Layer 1 . This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

extern volatile unsigned short 

lo_ph_sdu 


In OSI primitive received at 
Layer 2 from Layer 1 , the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

extern volatile unsigned short 

mjo _ph_sdu_offset 


In OSI primitive received at 
Layer 2 from Layer 1 , the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

extern volatile unsigned short 

mjo _ph_sdu_slze 


Size of the service data unit In 
an Interlayer-message buffer, 
displayed as SIZE on the Layer 
2 trace screen. Received at 
Layer 2 from Layer 1 . Same as 
datajength In a PDU. Line 
Setup configured for emulate or 
monitor mode. 

extern volatile unsigned short 

up_dl_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 


received at Layer 2 from Layer 
3. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 
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Table 66-3 (continued) 

Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile const unsigned char 

up_dl_prmtv_cade 

40/64 

42/66 

44/68 

48/72 

4a/74 

4c/76 

4e/78 

50/80 

52/82 

58/88 

dl conn req 
dl conn resp 
dl data req 
dl expd data req 
dl reset req 
dl reset resp 
dl dlsconn req 
dl debug req 
dl unit data req 
dl mgt facility req 




OSI primitive cods received at 
Layer 2 In a PDU from Layer 3. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned char 

up_dl_prmtv_path 

0-8 

Path number received at Layer 
2 In a PDU from Layer 3. Line 


Setup configured tor emulate 
mode only. 


extern volatile unsigned short 

up_dl_ll_buff 

Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 2 In a PDU 
from Layer 3. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

up_dl_sdu 

Offset to the start (header 
node) of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 2 from Layer 
3. Same as data_start_off$et In 
a PDU. Line Setup configured 
for emulate mode only. 

extern unsigned long 

12 tick count 

32— bit 11 tick count stored In 


header o7 most recent IL buffer 
passed up to Layer 2. 

Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 



configured for emulate or 
monitor mode. 
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Table 66-4 

Layer 3 OSI Variables 


Type 


Variable Value (hex/declmal) Meaning 


extern event 


lo_dl_prmtv 


extern event 


m_lo_dl_prmtv- 


extern event 


up_n_prmtv 


extern volatile unsigned short lo_dl _pdu_seg 


extern volatile unsigned short mJo_dl_pdu_seg 


extern volatile const unsigned char lo_dl_prmtv_code 


True when an OSI primitive Is 
received at Layer 3 from Layer 
2 . Line Setup configured for 
emulate mode only. 

True when an OSI primitive Is 
received at Layer 3 from Layer 
2. Line Setup configured for 
emulate or monitor mode. 

True when an OSI primitive Is 
received at Layer 3 from Layer 
4, Line Setup configured for 
emulate mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 3 from Layer 
2. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Lfne 
Setup configured for emulate 
mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 3 from Layer 
2. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


41/65 

dl 

43/67 

dl 

45/69 

di 

49/73 

dl 

4b/75 

dl 

4d/77 

dl 

4f/79 

dl 

51/81 

dl 

53/83 

dl 

55/85 

dl 

59/89 

dl 


conn Ind 
conn conf 
data ind 
expd data Ind 
reset Ind 
reset oonf 
dfsconn Ind 
debug Ind 
unit data ind 
error report Ind 
mgt facility Ind 


OSI primitive code received at 
Layer 3 In a PDU from Layer 2. 
Lfne Setup configured for 
emulate mode only. 
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Table 66-4 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile const unsigned char 

mJo_dl_prmtv_code 

44/6B 

45/69 

46/72 

49/73 

54/64 

55/85 

td dl data Ind 
rd dl data Ind 
td dl expd data ind 
rd dl expd data Ind 
td dl unit data Ind 
rd dl unit data Ind 

OSI primitive code received at 
Layer 3 In a PDU from Layer 2. 
Line Setup configured for 
emulate or monitor mode. 

extern volatile con9t unsigned char 

lo_dl_prmtv_path 

0-8 

Path number received at Layer 
3 in a PDU from Layer 2. UnB 
Setup configured for emulate 
mode only. 

extern volatile const unsigned char 

m_lo_dljJrmtv_path 

0-8 

Path number received at Layer 
3 in a PDU from Layer 2. Line 
Setup configured for emulate or 
monitor mode. 

extern volatile unsigned short 

lo_dlJI_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 3 In a PDU 
from Layer 2. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

m_!o_dl_l|_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 3 In a PDU 
from Layer 2. This segment 
number can be converted to a 
pointer by shifting it left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

extern volatile unsigned short 

lojjl_sdu 


In OSI primitive received at 
Layer 3 from Layer 2, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

extern volatile unsigned short 

m_lo_dl_sdu_offset 


In OSI primitive received at 
Layer 3 from Layer 2. the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

extern volatile unsigned short 

mJo_dl_sdu_slze 


Size of the service data unit in 
an Interlayer-message buffer, 
displayed as SIZE on the Layer 
3 trace screen. Received at 


Layer 3 from Layer 2. Same as 
datajenglh In a PDU, Line 
Setup configured for emulate or 
monitor mode. 
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Table 66-4 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile unsigned short 

up_n_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 3 from Layer 
4. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

extern volatile const unsigned char 

up_n_prmlv_code 

60/96 
62/98 
64/100 
66/102 
68/104 
6a/ 106 
60/ 108 
6e/110 
70/112 
72/114 
74/116 
76/118 
78/120 

n conn req 
n oonn resp 
n data req 
n data ack req 
n expd data req 
n reset req 
n reset resp 
n dlsconn req 
n debug req 
n unit data req 
n qual data req 
n qual data ack req 
n mgt facility req 




OSI primitive code received at 
Layer 3 In a PDU from Layer 4. 
Line Setup configured for 
emulate mode only. 

extern volatile oonst unsigned char 

up_n _prmtv_path 

0-8 

Path number reoelved at Layer 
3 In a PDU from Layer 4. Line 
Setup configured for emulate 
mode only. 

extern volatile unsigned short 

up_njl_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 3 In a PDU 
from Layer 4. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

up_n_sdu 


Offset to the start (header 
node) of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 3 from Layer 
4. Same as data_slart_oUse( In 
a PDU. Line Setup configured 
for emulate mode only. 

extern unsigned long 

l3_tlek_count 


32-bit H_tIck_coun( stored In 
header of most recent IL buffer 
passed up to Layer 3. 

Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-5 

Layer 4 OSI Variables 


Type 

Variable Value (hex/decimal) 

Meaning 


extern event 


lo_n_prmtv 


extern event 


mJ o _n_prmtv 


extern event 


up_t_prmtv 


extern volatile unsigned short lo_n_pdu_seg 


extern volatile unsigned short m_lo_n_pdu_seg 


extern volatile const unsigned char lo_n_prmtv_code 


True when an OSI primitive Is 
received at Layer 4 from Layer 
3. Line Setup configured for 
emulate mode only, 

True when an OSI primitive Is 
received at Layer 4 from Layer 
3. Line Setup configured for 
emulate or monitor mode. 

True when an OSI primitive Is 
received at Layer 4 from Layer 
5. Line Setup configured for 
emulate mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 4 from Layer 
3. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 4 from Layer 
3. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 


61/97 n 

63/99 n 

65/101 n 

67/103 n 

69/105 n 

6b/1Q7 n 

6d/109 n 

6f/1 1 1 n 

71/113 n 

73/116 n 

75/117 n 

77/119 n 

79/121 n 

7a/122 n 


conn Ind 
conn conf 
data Ind 
data ack Ind 
expd data Ind 
reset Ind 
reset conf 
dlsconn Ind 
debug Ind 
unit data Ind 
qual data Ind 
qual data ack ind 
mgt facility Ind 
error report Ind 


OSI primitive code received at 
Layer 4 In a PDU from Layer 3. 
Line Setup configured for 
emulate mode only. 
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Table 66-5 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


m_lo_n_prmtv_code 64/100 

65/101 

68/102 

69/103 

74/116 

75/117 


lo_n_prmtvj5ath 0-8 


mJo_n_prmtv_path 0-8 


lo_n_II_buff 


m lo n II buff 


lo n sdu 


m lo n sdu offset 


m lo n sdu size 


td n data Ind 
rd n data Ind 
td n expd data Ind 
rd n expd data Ind 
td n unit data Ind 
rd n unit data Ind 

OSI primitive code received at 
Layer 4 In a PDU from Layer 3. 
Line Setup configured for 
emulate or monitor mode. 

Path number received at Layer 
4 In a PDU from Layer 3. Line 
Setup configured for emulate 
mode only. 

Path number received at Layer 
4 In a PDU from Layer 3, Line 
Setup configured for emulate or 
monitor mode. 

Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 4 In a PDU 
from Layer 3. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 4 In a PDU 
from Layer 3. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

In OSI primitive received at 
Layer 4 from Layer 3, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

In OSI primitive received at 
Layer 4 from Layer 3, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

Size of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 4 from Layer 
3. Same as datajength In a 
PDU. Line Setup configured for 
emulate or monitor mode. 
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Table 66-5 (continued) 

Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile unsigned short 

up_t_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 




received at Layer 4 from Layer 
5. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

extern volatile const unsigned char 

up_t_prmtv_code 

80/128 

t conn req 


82/130 

t conn resp 



84/132 

t data req 



88/136 

t expd data req 



8e/142 

t dlsconn req 



90/144 

t debug req 



92/146 

t unit data req 



98/152 

t mgt facility req 




OSI primitive code received at 
Layer 4 In a PDU from Layer 5. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned char 

up_t_prmtv_path 

0-8 

. Path number received at Layer 
4 In a PDU from Layer 5. Line 
Setup configured for emulate 
mode only. 



extern volatile unsigned short 

up_t_ll_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 4 In a PDU 
from Layer 5. This segment 
number can be converted to a 




pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

up t sdu 


Offset to the start (header 




node) of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 4 from Layer 




5. Same as data start offset In 




a PDU. Line Setup configured 
for emulate mode only. 

extern unsigned long 

14 tick count 


32-blt 11 tlck_count stored In 



header of most recent IL buffer 




passed up to Layer 4. 
Preserves at each layer the 
original time when the end of 
the data (BCC) was clooked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 


JUL '90 


66-23 





INTERVIEW 7000 Series Advanced Programming : ATLC-1 07-951 -108 


Table 66-6 

Layer 5 OSI Variables 


Type 

Variable 

Value (hex/decimal) Meaning 

extern event 

lo_t _prmtv 


True when an OSI primitive Is 
received at Layer 5 from Layer 
4. Line Setup configured for 
emulate mode only. 

extern event 

mJo_t_prmtv 


True when an OSI primitive Is 
received at Layer 5 from Layer 
4. Line Setup configured for 
emulate or monitor mode. 

extern event 

up_s_prmtv 


True when an OSI primitive Is 
received at Layer 5 from Layer 
6. Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

lo_t_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 5 from Layer 
4. This segment number oan 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

extern volatile unsigned short 

m_lo_t_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 5 from Layer 
4. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Una 
Setup configured for emulate or 
monitor mode. 

extern volatile const unsigned char 

!o_t_prmtv_code 

81/129 

83/131 

85/133 

89/137 

8f/143 

91/145 

93/147 

95/149 

99/153 

t conn Ind 
t conn conf 
t data Ind 
t expd data Ind 
t dlsconn Ind 
t debug Ind 
t unit data Ind 
t error report Ind 
t mgt facility Ind 
OSI primitive code received at 
Layer 5 In a PDU from Layer 4. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned char 

mJo_t_p r mtv_code 

84/132 

85/133 

td t data Ind 
rd t data Ind 


88/136 td t expd data Ind 

89/137 rd t expd data Ind 

94/148 td t unit data Ind 

95/149 rd t unit data Ind 

OSI primitive code received at 
Layer 5 In a PDU from Layer 4. 
Line Setup configured for 
emulate or monitor mode. 
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Table 66-6 (continued) 


Type 

Variable Value (hex/declmal) 

Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


lo_t_prmtv _path 0-8 


m_lo_t_prmtv_path 0-8 


lo t II buff 


m_lo_t_ll_buff 


lo t sdu 


m lo t sdu offset 


m_lo_t_sdu_slze 


up_s_pdu_seg 


Path number received at Layer 
5 In a PDU from Layer 4 . Line 
Setup configured for emulate 
mode only. 

Path number received at Layer 
5 In a PDU from Layer 4. Line 
Setup configured for emulate or 
monitor mode. 

Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 5 In a PDU 
from Layer 4. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 5 In a PDU 
from Layer 4. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

in OSI primitive received at 
Layer 5 from Layer 4, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

In OSI primitive received at 
Layer 5 from Layer 4, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

Size of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 5 from Layer 
4. Same as datajength In a 
PDU. Line Setup configured for 
emulate or monitor mode. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 6 from Layer 
6. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 
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Table 66-6 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile const unsigned ohar 

up_a_prmtv_code 

a0/160 
a2/162 
a4/164 
a8/168 
ac/172 
ae/174 
bO/176 
b2/178 
b8/1 84 

s conn req 
s conn res p 
s data req 
s expd data req 
s release req 
s release resp 
s debug req 
s unit data req 
s mgt facility req 




OSI primitive code received at 
Layer 5 In a PDU from Layer 6. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned ohar 

u P_ 8 _Prmtv_path 

0-8 

Path number reoelved at Layer 
5 In a PDU from Layer 6. Line 
Setup configured for emulate 
mode only. 

extern volatile unsigned short 

up s U buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 5 In a PDU 
from Layer 6. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

up_s_sdu 


Offset to the start (header 
node) of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 5 from Layer 
6. Same as data_start_ot/set In 
a PDU. Line Setup configured 
for emulate mode only. 

extern unsigned long 

l5_t!ck_count 


32-blt l1_tlck_count stored In 
header of most recent IL buffer 
passed up to Layer 5. 

Preserves at each layer the 
original time when the end of 
the data (SCO) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-7 

Layer 6 OSI Variables 


Type 

Variable 

Value {hex/decimal) Meaning 

extern event 

l°_s_prmtv 


True when an OSI primitive Is 
received at Layer 6 from Layer 
5. Line Setup configured for 
emulate mode only. 

extern event 

mJo_a_prmtv 


True when an OSI primitive Is 
received at Layer 6 from Layer 
6. Line Setup configured for 
emulate or monitor mode. 

extern event 

up_p_prmtv 


True when an OSI primitive Is 
received at Layer 6 from Layer 
7. Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

lo_s_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 6 from Layer 
5, This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

extern volatile unsigned short 

m_lo_s_pdu_seg 


OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 6 from Layer 
5. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 

extern volatile const unsigned char 

io_s_prmtv_ c ode 

al/161 

a3/163 

a5/165 

a9/169 

ad/173 

af/175 

bi/177 

b3/179 

b5/181 

b9/18S 

s conn Ind 
s conn conf 
s data Ind 
s expd data ind 
s release Ind 
s release conf 
s debug Ind 
s unit data Ind 
s error report Ind 
s mgt facility Ind 
OSI primitive code received at 
Layer 6 In a PDU from Layer 5. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned char 

m_lo_s_prmtv_code 

a4/164 

a5/165 

td s data Ind 
rd s data Ind 


a8/16B td s expd data Ind 

aS/169 rd s expd data Ind 

b4/1 80 td s unit data Ind 

b5/181 rd s unit data Ind 

OSI primitive code received at 
Layer 6 In a PDU from Layer 5. 
Line Setup configured for 
emulate or monitor mode. 
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Table 66-7 (continued) 


Type 


Variable Value (hex/declmal) Meaning 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile unsigned short 


lo_s _prmtv_path 0-8 


mJo_s _prmtv_path 0-8 


lo s II buff 


m lo s II buff 


lo_s_sdu 


m lo s sdu offset 


m_lo_s_sdu_slze 


up_p_pdu_seg 


Path number received at Layer 
6 In a PDU from Layer 5. Line 
Setup configured for emulate 
mode only. 

Path number received at Layer 
6 In a PDU from Layer 5. Line 
Setup configured for emulate or 
monitor mode. 

Interlayer-buffer number {an 
IAPX-286 segment number) 
reoelved at Layer 6 In a PDU 
from Layer 6. This segment 
number oan be oonverted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

Interlayer-buffer number (an 
IAPX-286 segment number) 
reoelved at Layer 6 In a PDU 
from Layer 5. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

In OSI primitive received at 
Layer 6 from Layer 6, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

In OSI primitive received at 
Layer 6 from Layer 5, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

Size of the service data unit In 
an Interlayer-message buffer, 
Received at Layer 6 from Layer 
5. Same as datajength In a 
PDU. Line Setup"conflgured for 
emulate or monitor mode. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 6 from Layer 
7. This segment number oan 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 
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Table 66-7 (continued) 

Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile const unsigned char 

up_p_prmtv_code 

cO/192 
c2/194 
C4/196 
cS/200 
cc/204 
ce/206 
d0/208 
d2/210' 
d8/2 1 6 

p conn req 
p conn resp 
p data req 
p expd data req 
p release req 
p release resp 
p debug req 
p unit data req 
p mgt facility req 




OSI primitive code received at 
Layer 6 from Layer 7 In a PDU. 
Line Setup configured for 
emulate mode only. 

extern volatile const unsigned char 

up_p_prmtv_path 

0-8 

Path number received at Layer 
6 from Layer 7 In a PDU. Line 
Setup configured for emulate 
mode only. 

extern volatile unsigned short 

up_p_ll_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
reoelved at Layer 6 from Layer 
7 In a PDU. This segment 
number oan be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

up_p_sdu 


Offset to the start (header 
node) of the service data unit In 
an lnterlayer-mes6age buffer. 
Received at Layer 6 from Layer 
7. Same as data_start_off$et In 
a PDU. Line Setup configured 
for emulate mode only. 

extern unsigned long 

l6_tlck_count 


32-blt lljlckjcount stored In 
header of most recent IL buffer 
passed up to Layer 6. 

Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Line Setup 
configured for emulate or 
monitor mode. 
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Table 66-8 

Layer 7 OSI Variables 


Type 


Variable Value (hex/decimal) Meaning 


extern event 


extern event 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern volatile const unsigned char 


lo_p_prmtv 


mJo_p_prmtv 


lo_p_pdu_seg 


mjo _p_pdu_eeg 


lo_p _prmtv_code cl/193 

03/195 
C5/197 
C9/201 
cd/205 
cf/207 
di/209 
d3/21 1 
d5/213 
d9/217 


m_lo_p_prmtv_code C4/196 

C5/197 

C8/200 

C9/201 

d4/2l2 

d5/213 


lc_p_prmtv_path 0-8 


True when an OSI primitive Is 
received at Layer 7 from Layer 
6. Line Setup configured for 
emulate mode only. 

True when an OSI primitive Is 
received at Layer 7 from Layer 
6. Line Setup configured for 
emulate or monitor mode. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 7 from Layer 
6. This segment number oan 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate 
mode only. 

OSI primitive data unit (PDU) 
IAPX-286 segment number 
received at Layer 7 from Layer 
6. This segment number can 
be converted to a pointer by 
shifting It left 16 bits. Line 
Setup configured for emulate or 
monitor mode. 

p conn ind 
p conn conf 
p data Ind 
p expd data Ind 
p release Ind 
p release conf 
p debug Ind 
p unit data Ind 
p error report Ind 
p mgt facility Ind 

OSI primitive code received at 
Layer 7 In a PDU from Layer 6. 
Line Setup configured for 
emulate mode only. 

td p data Ind 

rd p data Ind 

td p expd data Ind 

rd p expd data Ind 

td p unit data Ind 

rd p unit data Ind 

OSI primitive code received at 

Layer 7 In a PDU from Layer 6. 

Line Setup configured for 

emulate or monitor mode. 

Path number received at Layer 
7 In a PDU from Layer 6. Line 
Setup configured for emulate 
mode only. 
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Table 66-8 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

extern volatile const unsigned char 

m_lo_p_prmtv_path 

0-8 

Path number received at Layer 
7 In a PDU from Layer 6. Une 
Setup configured for emulate or 
monitor mode. 

extern volatile unsigned short 

lo_p_ll_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 7 In a PDU 
from Layer 6. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate mode only. 

extern volatile unsigned short 

mjo _p_ll_buff 


Interlayer-buffer number (an 
IAPX-286 segment number) 
received at Layer 7 In a PDU 
from Layer 6. This segment 
number can be converted to a 
pointer by shifting It left 16 bits. 
Line Setup configured for 
emulate or monitor mode. 

extern volatile unsigned short 

lojD_sdu 


In OSI primitive received at 
Layer 7 from Layer 6, the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate mode only. 

extern volatile unsigned short 

m_lo_p_sdu_offset 


In OSI primitive received at 
Layer 7 from Layer 6. the offset 
to where the service data unit 
begins. Line Setup configured 
for emulate or monitor mode. 

extern volatile unsigned short 

m_lo_p_sdu_size 


Size of the service data unit In 
an Interlayer-message buffer. 
Received at Layer 7 from Layer 
6. Same as data length In a 
PDU. Line Setup configured for 
emulate or monitor mode, 

extern unsigned long 

l7_tlck_count 


32— bit lljlck count stored In 
header of most recent IL buffer 
passed up to Layer 7. 

Preserves at each layer the 
original time when the end of 
the data (BCC) was clocked 
Into the buffer. Une Setup 
configured tor emulate or 
monitor mode. 


66.3 Routines 

OSI routines available at each layer make sending primitives to a layer above or 
below possible (see Figure 66-3). The routine name and its arguments provide the 
same information as the softkey selections on the Protocol Spreadsheet. (In the early 
phases of compiling the program, the C translator uses the routines to convert the 
spreadsheet softkey-token primitives into C.) All routines are protocol-independent. 
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(A) Layer-Independent OSI Routines 

The following interlayer buffer service routines operate at any layer, regardless of 
protocol (or in the absence of a protocol package). 

_getjl_msg_buff 

Synopsis 

extern void ^get_il_msg_buff (buffer _n umber jptr, malntain_bit _ptr); 
unsigned short * buffer jtumber _ptr; 
unsigned short • maintain_bil _ptr; 

Pescnption 

The _get_il_msg_buff routine gets a free interlayer message buffer from the pool 
and returns the buffer number to the caller for use in subsequent calls to other 
interlayer buffer services. It also returns a maintain bit for use in the freeing 
operation. 

Inputs 

The first parameter is a pointer to the location where the buffer number is to be 

stored. The buffer number that is returned is actually an iAPX-286 segment 

number which can be converted to a pointer by shifting it 16 bits to the left. If ( 

there is no free buffer available, the routine will wait for one to become 

available. 

The second parameter is a pointer to the location where the maintain bit will be 
stored. Since it must be used in the freeing operation, the maintain bit value 
should not be modified. The zero bit in this variable indicates your maintain 
bit. 

Example 

The variables in which the returned buffer number and maintain bit will be 
stored must be declared. When calling the routine, reference the addresses of 
these variables. 

{ 

unsigned short ii_buffer_number; 
unsigned short relay_baton; 

> 

LAYER: 4 

STATE: get_a_buffer 

CONDITIONS: KEYBOARD * ” 

ACTIONS: 

{ 

_get_ll_msg_buff(&il buffer_number, &relay_baton); 

) 

The routine will get a buffer number and store it in variable il_buffer_number. 

It will also return a maintain bit and store it in variable relay_baton. 
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start Jl_buff_list 


Synopsis 

extern void _startjl_buff_llst(il_buffer_number, start_offset _plr); 
unsigned short il_buffer_number; 
unsigned short * start_offset _ptr; 


Description 

The _start_il_buff_list routine starts a linked list of text inside an interlayer 
message buffer. The list is made up of a header node and text nodes. The 
header node contains offsets to the first and last text nodes. Each text node 
contains a pointer to the actual text, the length of the text, and the offset to the 
next text node. This routine actually creates the header node inside the 
interlayer message buffer and initializes the first and last text node offsets to 
zero, indicating an empty list. It will return the offset to the list header node for 
use in subsequent list service calls. 


Inputs 

The first parameter is the interlayer message buffer number that will contain the 
list. 

The second parameter is a pointer to the location where the offset to the list 
header will be stored. The returned offset will be zero if there is insufficient 
room in the buffer for the header node and one text node. Otherwise, it is the 
offset from the beginning of the message buffer to the start of the header node. 

To convert the offset into a pointer, shift the buffer number 16 bits to the left 
and add the offset: 

(void *)(((long)il_buffer_number « 16) + data_start_offset); 


E xa m p le 

Get a buffer and start a linked list. The variable in which the returned offset 
will be stored must be declared. When calling the routine, reference the address 
of this variable. 

{ 

unsigned short HJbufferjtumber; 
unsigned short relay baton; 
unsigned short data_start_offset ; 

) 
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STATE: 9tart_a_ll$t 

CONDITIONS: KEYBOARD “ ” 

ACTIONS: 

{ 

_getjljnsg_buff (&iljbufferjtumber, &re!ay_baton) ; 
_starljlj>uffjist(il_bu}fer_number, &data_startj>fjset); 

/• See JnsertJlJbuffJistjnt routine on how information is inserted in the buffer. */ 

} 

The routine will get the offset to the header node and store it in variable 
data_start_offset . 

_dup_il_buff_llst_start 

Svaopsis 

extern unsigned short _dup_i!_buff_llsl_start(il_buffer_number, start joff set, 
new_start_offset _ptr); 
unsigned short il_buffer_number; 
unsigned short slart_offset; 

unsigned short * new_start_offset _plr; , 

Description 

This routine duplicates the header node of a pointer list. In order for a layer to 
retain the ability to resend a buffer— that is, to reference again the same list 
header with the same first-node offset— it must keep its own linked list safe from 
data inserted at a layer below. The jhipjl_buffjist_start routine allows the 
lower layer to start its own list. 

If the lower layer will insert data into the buffer, it need duplicate only the list 
header (“ listjstart ”), not the entire list. If the layer will append data to the 
end of the buffer, it must duplicate the complete linked list via the 
jiupJlJ) u ffjis t routine. 

Inputs 

The first parameter is the interlayer message buffer number in which the header 
node will be duplicated. 

The second parameter is the offset to the header node to be duplicated. 

The third parameter is a pointer to the location where the offset to the new 
header node will be stored. 

Returns 

This routine returns zero if there is not enough room in the buffer for the 
duplicated header node and at least one list node. 
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Duplicate the header node of a buffer passed down from Layer 3 . 
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i 

extern volatile unsigned short up_dljl_buff; 
extern volatile unsigned short upjdl_sdu; 
unsigned short 12 data start offset; 

I 

LAVER: 3 

STATE: message 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: DL_DATA REQ “RAMFOX)) " 

LAYER: 2 

STATE: dupllcate_header 

CONDITIONS: DLJ3ATA REQ 
ACTIONS: 

{ 

_dupjl_buffjist_start(up^dl_il_buff, up_dl_sdu, &l2_data_start_offset ); 

/* See Jnsert_il_buff_list_cnt routine on how information is inserted in the buffer. *1 

) 

_dup_II_buff_list 

Synopsis 

extern unsigned short jdup_il_bu}fJist(U_buffer_number, start ^offset, new_start_offset _ptr); 

unsigned short tljbuffer_number; 

unsigned short start_offset; 

unsigned short * new_start_offset _ptr; 

P^npllQQ 

This routine duplicates an entire pointer list. In order for a layer to be able to 
retain the ability to resend a buffer— that is, to reference again the same list 
header with the same first- and last-node offsets— it must keep its own linked 
list safe from data inserted and appended at a layer below. The 
_dup_il_buff_list routine allows the lower layer to have its own list. 

If the lower layer will append data to the buffer, it should duplicate the entire 
linked list. If the layer will only insert data into the buffer, it need only 
duplicate the header node via the _dupjl_buff_list_start routine. 

Inputs 

The first parameter is the interlayer message buffer number in which the list will 
be duplicated. 

The second parameter is the offset to the header node of the list to be 
duplicated. 
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The third parameter is a pointer to the location where the offset to the header 
node for the new list will be stored. 

Reiums 

This routine returns zero if the duplication is successful. If there is not enough 
room in the buffer to duplicate the list, one is returned. 

Example 

Duplicate the entire pointer list of a buffer passed down from Layer 3. 

< 

extern volatile unsigned short up_dl Jl^bu/f; 
extern volatile unsigned short up_dl_sdu; 
unsigned short l2_data_start_offset; 

) 

LAYER; 3 

STATE: message 

CONDITIONS: KEYBOARD “ " 

ACTIONS: DL_DATA REQ "°,A'&«FOX)) ’ 

LAYER: 2 

STATE: duplicate Jlst 

CONDITIONS: DL_DATA REQ 
ACTIONS: 

{ 

jdupJI_buffJist(up_dljl_buff, up_dl_sdu, &!2_data_start_offset); 
l A See _append Jl _buff_list_cnt routine on how informalion is appended lo the buffer. •/ 

} 

_open_space_in_il_buff 

Synopsis 

extern void _open_space_in_il_buff(il_buf/er_number, length, space_offset_ptr); 

unsigned short il_buffer_number; 

unsigned short length; 

unsigned short ’ spacejoffset _ptr; 

EeagrjpUQa 

The _opert_spacejn_il_buff routine opens up the requested amount of space in 
the specified interlayer message buffer. It returns an offset from the beginning 
of the buffer to the start of the open space. 

Inputs 

The first parameter is the interlayer message buffer number in which space is to 
be made. 
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The second parameter is the amount of space (number of bytes) requested. 

The third parameter is a pointer to the location where the returned offset will be 
stored. The returned offset will be zero if there is insufficient room in the 
buffer. 

To convert the offset into a pointer, shift the buffer number 16 bits to the left 
and add the offset: 

(void *) ( ( (long) ll _buj fern umber « 16) + avallable_space_offset); 

Example 

Always open space in the buffer if you are going to copy data (usually header 
information) into the buffer. If you are not going to copy data into the buffer, 
but reference its location in memory outside the buffer (usually user data), you 
do not need to open space. 

The variable in which the returned offset will be stored must be declared, When 
calling the routine, reference the address of this variable. The length may be 
entered as a numeric value, in which case a length variable need not be 
declared. 

For example, a buffer at Layer 3 will have three X. 25-header bytes inserted. 

The call for space to hold the header would look like this: 

1 

unsigned short ll_buffer_number; 
unsigned short relay Jbaion; 
unsigned short data_start_offset; 
unsigned short available_space_offset; 

) 

STATE: get_space 

CONDITIONS: KEYBOARD “ " 

ACTIONS: 

{ 

_getjl_msg bujf(&il Jruffer _number, &relay_baton); 
_start_il_buffjist(il_buffer_number, &data_start_offset); 

_open space _in _il _buff (il _bujfer _number , 3, &available_space_offsel) ; 

/* See _insert_il_buff_list__cnt routine on how information Is Inserted in the buffer. */ 

) 

The routine will get the offset to the next available space in the buffer and store 
it in variable available _space_offset. 

Once space has been opened, the buffer-number and available-space variables 
can be converted into an open-space pointer. With this pointer, data can be 
copied into the space. The pointer can then be referenced in an 
_inser(_il_buffjist_cnt routine, so that the opened space becomes threaded onto 
the linked list in the IL buffer. See the programming example under 
_insert_il_buff_list_cnt. 
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_freejl_msg_buff 

Synopsis 

extern void _freejl_msg_bu/f(il_bu//er_number, reiay_baton); 
unsigned short ll_bu/fer_number; 
unsigned short relay^baton; 


Des cr iption 

The J'reejl_msg_buff routine returns an interlayer message buffer to the pool of 
free buffers. Before actually returning the buffer to the pool, this routine 
verifies that all maintain bits have been reset, assuring that all users have freed 
this buffer. 

Inputs 

The first parameter is the interlayer-buffer number to be freed. 

The second parameter is the maintain bit associated with the buffer user to be 
freed. 

Example 

See _set_maint _buff_bit routine. 

_set_maintj}uff_bit 


Synopsis 

extern void _set_maint_buff_bit(U_buffer_number, newjblt _ptr); 
unsigned short H_buffer_number; 
unsigned short * new_bit _ptr; 

Description 

The _set_maintj>uffj>it routine sets a new maintain bit for a given interlayer 
message buffer. It returns that bit to the caller to be used in the freeing 
operation. 

The maintain bit allocated in the _getjljnsg_buff routine should be considered 
valid only for the layer at which it was obtained. Once you pass a buffer, the 
maintain bit will hold the buffer at the next layer only until action on it has been 
processed. (In Spreadsheet terms, the buffer will be held until the ACTIONS 
block has been processed in response to the first conditions block identifying 
the buffer. In any other CONDITIONS block referring to the buffer, the buffer 
will not be found unless an additional maintain bit was set.) The maintain bit 
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eventually will be freed automatically whether or not any action is taken on it at 
the next layer. To hold a buffer at a particular layer, or to continue passing the 
buffer (in either direction), a new maintain bit must be set. The same maintain 
bit cannot be used continuously, since it will be freed after the first process on it 
(an action to send, for example). 

If you wish to keep a buffer available for your use while also sending it to 
another layer, set two maintain bits. One will be used to pass the buffer; the 
other will “maintain" the buffer for other processes. The latter will have to be 
freed via the _free_il_msg_buff routine. 

Inputs 

The first parameter is the interlayer-buffer number in which the new bit will be 
set. 

The second parameter is a pointer to the location where the returned maintain 
bit will be stored. There are sixteen maintain bits reserved for each interlayer 
buffer. Each bit is identified by a two-byte variable with a single zero. The first 
maintain bit allocated is the least significant, so the value returned is 
hexadecimal FFFE (binary 11111111 11111110). The last maintain bit 
allocated is 7FFF (01111111 11111111). If all the maintain bits are already in 
use, FFFF will be returned. 

The maintain bit value should not be modified. It must be used in the freeing 
operation to make sure the buffer is returned to the free buffer pool. 

Example 

The variable in which the returned maintain bit will be stored must be declared. 
When calling the routine, reference the address of this variable. For example, 
you receive a buffer at Layer 2 from Layer 3 (up_dl_iljbuff) and insert 
information into it. Before passing the buffer to Layer 1, set two maintain bits. 
The one stored in variable maintain_bit will hold the buffer for the purpose of 
repeated resends of the frame, if necessary, and will have to be freed via the 
_free_il_msg_buff routine. When you pass the buffer down, use the bit in 
variable l2_relay_baton. When you resend the frame, set a new resend_baton 
bit and pass that down, still holding maintain_bit in reserve for subsequent 
resends. 

{ 

unsigned short l2j r elay_baton ; 

unsigned short resend _baton; 

unsigned short maintain_bh; 

extern volatile unsigned short up_dljl_bujf; 

extern volatile unsigned short up_dl_sdu; 

unsigned short l2_data_start_offset; 

unsigned short available _space_offset; 

static unsigned char 12 _data[2) = {0x01, 0x00); 

int i; 

unsigned char ' ptrJ2; 
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# define make j>tr(number, offset) ( (void ') (((long) number « 16) + offset )) 

) 

LAYER: 3 

STATE: sendJox_message 
CONDITIONS: KEYBOARD ■ " 

ACTIONS: DL_DATA REQ "‘I'VMFOX)) " 

LAYER: 2 

STATE: send_a_buffer 

CONDITIONS: DL_DATA REQ 
ACTIONS: 

< 

/• See JnsertJl_buff_Ust_cnt routine for an explanation of how information is inserted in the 
buffer. V 

dup_it_buff_list_start (up_dl_il_buff, up_dl_sdu, &l2_data_start_offset); 
_open_space_lnjl_buff(up_dlJl_buff, 2, <&available_space_offset); 
plr_t2 = make _ptr(up_dl_il_buff, available_space_offset) ; 
for(i = 0; I < 2; i++) 

< 

*ptr_l2 = data_!2ll]; 
ptrj2+i; 

) 

ptr_12 -=2; 

_insert_llj}uffjist_cnt(up_dl_il_buff, l2_data_start_offsei, ptr_!2, 2); 
_set_maint_buff_bit(up_dl_il_buff, &maintain_bit); 

_set_mainl_buff_blt(up_dl_ilj>uff, &!2_relayJ>aton); 

send _ph _prmtv be!ow(up_dt il_buff, 12 relay baton, 12 data _start_of f set, 0, 0x24, 0); 

} 

LAYER: 1 

STATE: resend_buffer 

CONDITIONS: RECEIVE STRING CCXXXX1 001 » “ 

ACTIONS: 

{ 

_set _malnt _buffj>i t(up_dl_il_buff, &resend_baton ) ; 
ll_iljransmit(up_dl_UJ}uff, resend_baton, l2_data_start_offset, 1); 

/* See Section 62, Monitor/Transmil Line Data, for an explanation of the UJIJransmlt 
routine. */ 

} 

CONDITIONS: RECEIVE STRING “(E@((XXXX0001)) * 

ACTIONS: 

{ 

_Jree_li_msg_buff (up dljl btiff, malntaln_bit); 

/• See Jreejl jr\sg_buff for an explanation of this routine. */ 

} 

_insert_ll_buffjlst_cnt 

&[nflI2£i3 

extern unsigned short JnsertJi_buffJisl_cnt(ilJ>uffer_number, dalajstart_offset, textjrtr, 
lextjength); 

unsigned short il_bufferjtumber; 
unsigned short data^startjoffset; 
unsigned char * text _ptr; 
unsigned short textjength; 
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Description 

The _inserijl_buffjlst_cnl routine inserts a text node at the beginning of a 
linked list of text inside of an interlayer message buffer. It will set the text 
pointer and byte-count in the text node to the values specified. 

Inputs 

The first parameter is the interlayer-buffer number in which the linked list will 
be inserted. 

The second parameter is the offset to the header node for the linked list, from 
the beginning of the buffer. 

The third parameter is a pointer to a text. 

The fourth parameter is the length of the text. 

Bernina 

If the insert is successful, a value of 0 is returned; if it is not successful, a value 
of 1 is returned. If you want to check the returned value, do so at the time the 
routine is called, as in the following example at Layers 2 and 3. 

Saampje 

If text is to be copied into the buffer, a pointer to the text must be declared. If 
not, when calling the JnsertJl_buff_list_cnt routine, reference the address of 
the text. The length of the text may be entered as an integer, in which case a 
length variable need not be declared. 

Always open space in the buffer if you are going to copy data (usually header 
information) into the buffer. If you are not going to copy data into the buffer, 
but reference its location in memory outside the buffer (usually user data), you 
do not need to open space. 

In the following spreadsheet example, an interlayer-buffer number is obtained at 
Layer 5, a header node is created in the buffer, and the address of a fox 
message text (located in memory outside of the buffer) is inserted into a text 
node in the buffer. 

{ 

unsigned short il_bujferjtumber; 
unsigned short relay_baton; 
unsigned short l4_relay_balon 
unsigned short !3_relay_baton; 
unsigned short l2^relay_baton; 
unsigned short data_start_offset; 
unsigned short l2_data_slart_offset; 
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unsigned short avaitable_space~pffset; 
static unsigned char data[] = "((FOX))”; 
static unsigned char I3_dala[3] = { 0x10 , 0x04, 0x00); 
static unsigned char I2_data(2] = {0x01, 0x00); 
int i; 

int length; 

extern volatile unsigned short up_tjt_buff; 
extern volatile unsigned short up_n_ilj>uff; 
extern volatile unsigned short up_dl_U_buff; 
extern volatile unsigned short upjtjsdu; 
extern volatile unsigned short up_dl sdu; 
extern volatile unsigned short up_t_sdu; 
unsigned char * ptr_l3, * ptr_!2; 

/* Whenever make _ptr is encountered, the first parameter will be shifted 16 bits to the left. 

The second parameter will be added, and the result casl Into a pointer. */ 

Udefine make _plr(number, offset) ((void *) (((tong)number « 16) + offset)) 

) 

LAYER: 5 

STATE; begln_message 

CONDITIONS: KEYBOARD “ ■ 

ACTIONS: 

{ 

_get_il_msg_buff(&il_buffer_number, &relay_baton); 
_start_iljbuffjist(ilj)uffer_number, <Scdata_start_offsel); 

/* Do not include the terminating null character in the length determination of a string. */ 

length = sizeof(data) - 1; 

/* The address of data outside of the buffer is given for Insertion. The data itself Is not copied 
into the buffer. The buffer is then passed down to Layer 4 (see send_t _prmtv_below for an 
explanation of this routine). */ 

_insertjl_buffjist_cnt(il_buffer_number, data_start_offset, Adata/O], length); 
send t jjrmiv_below(il_buffer_number, relay baton, data_start_offset, 0, 0x84, 0); 

} 

At Layer 4 a new maintain bit is set to use in passing the buffer to Layer 3. 
Since no data is inserted, the same data_start_offsel is used (in the form of the 
variable up_t_sdu). The buffer is then passed down to Layer 3 (see 
send_n j>rmtv_below for an explanation of this routine). 

LAYER: 4 

STATE: pass 

CONDITIONS: T_DATA_REQ 
ACTIONS: 

< 

_set_maintJ>uff_bit(upj_U_buff, &14 _retay_baton); 

send_n _prmtv_be!ow(up_t_il_buff, !4_relay_baton, upjtjsdu, 0, 0x64, 0); 

} 

At Layer 3, space is opened for an X.25 packet header. A pointer to the 
opened space is created and the data is inserted into the linked list passed down 
from Layer 4. 
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LAYER: 3 

STATE: lnsert_and_send 

CONDITIONS: N_DATA_REQ 
ACTIONS: 

< 

_ppen_space_ln_U_buff(up_n_U_buff, 3, &avallabte_space_offset) ; 
ptrj 3 = make _plr(up_n_ll_buff, available _space_offset) ; 
for (I = 0; i < 3; /++) 

{ 

•ptr_!3 = I3_dala[i); 
plrJ3*4; 

) 

I* The location of the data in the buffer is referenced in the insert routine, so the pointer must 
be moved back to the beginning of the opened space. The offset to the Layer 3 header node is 
given in the insert routine. If the insertion is not successful, an alarm will sound and a message 
will be displayed on the prompt line of the screen. V 

plrJ3 -=3; 

Iff insert JI_buffJist_cnt(up_n_ll buff, up n_sdu, ptr 13, 3) /= 0) 

{ 

sound_alarm (); 

display _prompt ("Insert failed at Layer 3."); 

) 

/* A new maintain bit is set for passing the buffer. The buffer is then passed down to Layer 2 
(see sendjii j>rmtvJ>elow for an explanation of this routine). */ 
_set_maint_buff_bit(up_n_ilj>uff, &13 _relay_baton) ; 
send_dl _prmtv_below(up n_il_buff, 13 relayjbaton, up_n_sdu, 0, 0x44, 0); 

) 

At Layer 2, a new linked list is started. The Layer 2 header could be inserted 
into the linked list passed down from Layer 3; but if Layer 3 wants to retain the 
ability to resend a buffer— that is, to reference again the same list header with 
the same first-node offset— it must keep its own linked list safe from data 
inserted at Layer 2. 

LAYER: 2 

STATE: lnsert_more 

CONDITIONS: DL_DATA_REQ 
ACTIONS: 

{ 

/• The jiupji_buff_lisi_start routine allows Layer 2 to start its own list. Part of this routine 
copies the Layer 3 header into the Layer 2 header node. *1 

dup_HJ>uff list_start(up_dl_il_buff, up_dl_sdu, &l2_data_start_offset); 

I* Space Is opened in the buffer. A pointer to this location is created and the data is copied 
into the buffer. */ 

_open_space_in_U_buff(up_dl_llJ>uff, 2, &availabie_space_offset); 
ptrJ2 = make __ptr(up_dljl_buff, available space _off set); 
forfi = 0; 1 < 2; /++) 

{ 

*ptr_l2 = I2_data[l); 
pfr_i2++; 

} 

/* The location of the data in the buffer is referenced in the insert routine, so the pointer must 
be moved back to the beginning of the opened space. The offset to the Layer 2 header node is 
given in the insert routine. If the insertion is not successful, an alarm will sound and a message 
will be displayed on the prompt line of the screen. */ 
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ptrj2 ~-2; 

lf( insert Jl buff list cnt(up_dljl buff, l2_data_start_offset, ptrJ2, 2) 1= 0) 

{ 

sound_alarm(); 

pos_cursor(0,30); 

displaysf" Insert failed at Layer 2."); 

} 

/* A new maintain bil is sei for passing the buffer. The buffer is then passed down to Layer 1 
(see send _ph _prmtvJbelow for an explanation of this routine). */ 

_set_m aint_buff_bi t ( up_dljl_buff, & !2_relay_baton ) ; 

send _ph _prmtv_below(up_dl_il_buff, l2_retay_baton, I2_dala_start offset, 0, 0x24, 0); 

) 

The following text will be sent out onto the line and displayed as line data: 
^HiIS'HiTHE QUICK BROWN FOX JUMPS OVER THE LAZY DOG 0123456789^ 

_appendjl_buffjlst_cnt 

Synopsis 

extern unsigned short _appendjljbuffjist_cnt(ilj>uffer_number, data_start_pffset, text _ptr, 
textjength); 

unsigned short ll_buffer_number ; 
unsigned short data_starl_offset; 
unsigned char * text _ptr; 
unsigned short textjength; 

Description 

The j3ppend_il_buffjist_cnt routine appends a text node at the end of a linked 
list of text inside of an interlayer message buffer. It will set the text pointer and 
count in the text node to the information provided. 

Inputs 

See Jnsert_il_buff_Iist_cnt routine. 

Returns 

See Jnsert_il_buffJist_cnt routine. 

Example 

Two modifications to the program shown for the _insert_il_buff_list_cnt routine 
are all that is required to make the program work for appending data. The 
changes primarily involve Layer 2 in the example, so we will replicate only that 
portion of the program below. Substitute _append_il_buffjistj:nt for every 
occurrence _jnsertjl_bttff_lisl_cn t . When data is to be appended in a buffer, 
you should duplicate the entire linked list received from the layer above, not just 
the header node. So also substitute _dupjl_buff_list for _dupjl_buf/_list_start. 


66-44 


JUL ’90 




LAYER: 2 

STATE: Insert more 

CONDITIONS: DL_DATA_REQ 
ACTIONS: 

{ 

_dupjl_buffjist(up_dljl_buff, up_dl_sdu, &l2_data_start_offset); 
_ 0 pen_spacejn_il_buff(up_dljl_buff, 2, &avallable~spacejoffset) ; 
ptrJ2 = make _ptr{up_dljl_buff, avaiiable_space_offset); 
for(t = 0; 1 < 2; I++J 
{ 

*plrJ2 = I2_daia[i); 
ptr_l2++; 

) 

ptr_l2 -=2; 

tf( append il_buffjlst_cnt(up_dljl buff, 12 data start offset, ptrJ2, 2) 1= 0) 

1 

sound _alarm(); 
pos_cursor(0,30); 

dlsplaysf" Insert failed at Layer 2.’’); 

} 

_ set_maint_buff_bit(up_dlJH_buff , &\2_relay_ba ton); 

send _ph _prmtv below (up_dl_it_buff, !2_relay_baton, I2_data_start offset, 0, 0x24, 0); 

) 


The following text will be sent out onto the line and displayed as line data: 


THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG 0123456789 c LS- , i^ , i%[sl 


(B) Layer 1 OSI Routines 

OSI data primitives are handled automatically between Layers 1 and 2. In the 
"up” direction, line data is placed in an IL buffer and the associated data 
primitive is given automatically to Layer 2. In the “down" direction, data 
primitives are received at Layer 1 and put out automatically onto the line. 

In the absence of line data, if you want to originate a buffer at Layer 1 and 
send it upward, use the following routine. In primitives being sent down the 
layers, Layer 1 will automatically send the primitive out onto the line. 

send_ph_to_above 

Synopsis 

extern void send _ph_to_above(il_buffer_number, relayjbaton, data _start_off set, size, code, 
path); 

unsigned short il_buffer_number; 
unsigned short relayjbaton; 
unsigned short data_start_offset; 
unsigned short size; 
unsigned char code; 
unsigned char path; 
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Pe5ci.ipti£Ln 

The send _ph_to_above emulate routine passes a specified interlayer message 
buffer from Layer 1 to Layer 2 in an OSI primitive. Received line data is 
placed in an IL buffer and passed automatically to Layer 2. If you wish to get a 
buffer “manually” at Layer 1 and then pass it up, use this routine. 

Inputs 

The first parameter is the interlayer buffer number returned by the 
_getjl_msg_buff routine. 

The second parameter is the returned maintain bit from the J}et_il_msg_buff 
routine. As soon as Layer 2 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the returned offset (from the call to _start_il_buff_list) to 
the Layer 1 service data unit in a buffer. 

The fourth parameter is the length of the data in the buffer. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo _ph _prmtv _code in Table 66-3 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. 
Example 

Gel a buffer at Layer 1. Assuming X.25 protocol, insert data into the buffer 
and pass it up to Layer 2. 

{ 

unsigned short \l_buffer_number, 
unsigned short relay _balon; 
unsigned short data_start_offset; 
unsigned short availabte_space_offset; 

Int length; 
tnt i; 

static unsigned char data[J - {0x01, 0x00, 0x10, 0x04, 0x00, 0x02, 0x01, 0x01); 
unsigned char * ptr; 

} 

LAYER: 1 

STATE: get_buffer 

CONDITIONS: KEYBOARD “ ” 

ACTIONS: 

{ 

_gelji_msg_buff(&ilj>uffer_number, <Sirelay_baton); 
start _il_bujfjist (il_bu/fer_number, &data_$tart_offset) ; 
length = sizeof(data) ; 

_open_space_in_il_buff(il_buffer_number, length, &avallabte_space_offset) ; 
ptr = (void *) (((long)il_bu/fer_number « 16) + availabte_space_offset); 
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for(i = 0; K length; h+) 

{ 

* ptr = datajlj; 
ptr**; 

> . 

ptr--length; 

JnsertJl_buff_llst_cnt(ilJ>uffer_number, data _start_off set, ptr, length); 

send _ph_to_above(U_buJJer_number, relay J>aton, data_start_offset, length, 0x25, 0); 


(C) Layer 2 OSI Routines 

The following routines pass OSI primitives from Layer 2 to either Layer 3 or 
Layer 1. 


send_dl_prmtv_above 

Synopsis 

extern void send_dl j>rmlv_above(il_buffer_number, l2_relay_baton, l2_data_start_offset, size, 
!2_code, path); 

unsigned short H_buffer_number; 
unsigned short !2^relay_baton; 
unsigned short l2_daia_jtart_offset; 
unsigned short size; 
unsigned char l2_code; 
unsigned char path; 


Descri ptio n 

The send^dl _prmtvjabove emulate routine passes a specified interlayer message 
buffer from Layer 2 to Layer 3 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 2 from Layer 1, the variable lo _phjl_buff 
may be used to identify the buffer number. 

The second parameter is the returned maintain bit from a call to 
_seljnaint_buff_bit. It is used only to pass a received buffer from Layer 2 to 
Layer 3. As soon as Layer 3 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the offset to the Layer 2 service data unit in a received 
buffer. The variable lo j>h_sdu contains the offset to the service data unit when 
the buffer reached Layer 2. The offset must be incremented by the length of 
the Layer 2 header. 
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NOTE: In general, do not modify extern variables, such as 
to _ph_sdu , which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable, Or, after lo _phjsdu has been named in the 
argument of the send routine, add the length of the Layer 2 
header, as in the example below. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure— pdu.datajength. Then subtract the length of the 
Layer 2 header. 


The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo_d l jprmtv _code in Table 66-4 for the 
appropriate primitive code. 


The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 2 from Layer 1, the variable 
lo j>h _prmtv _path may be used to specify the path number. 


Example 

A buffer is received at Layer 2 from Layer 1. Assuming X.25 protocol, the 
data specific to Layer 2 (the frame header) begins at the SDU offset 
(lo _ph_sdu) and consists of two bytes. Before the buffer is passed up to Layer 3, 
the offset to the SDU and the size of the SDU will be adjusted by two bytes and 
a new maintain bit will be set. 

{ 

struct pdu 

{ 

unsigned char prtmitive_code ; 
unsigned char path; 
unsigned tong parameter; 
unsigned short relay_baton; 
unsigned short il_buffer_number; 
unsigned char buffer _contents; 
unsigned short data_start_offsel; 
unsigned short datajength; 

struct pdu * pdu _ptr; 

extern volatile unsigned short lo _ph _pdu_seg ; 
extern volatile const unsigned char lo _ph _prmtv _path; 
extern volatile unsigned short lo _ph_il_buff; 
extern volatile unsigned short lo _ph_sdu; 
unsigned short l2_relay_baton; 

) 


66-48 


JUL ’90 



66 0SI 


LAYER; 2 

STATE: send_buffer_up 

CONDITIONS: PH_DATA IND 
ACTIONS: 

{ 

pdu _plr = (void *)( (long)lo _ph _pdu_seg « 16); ■ 
_sei_maint_buff_bit(lo _ph_ll_buff, AI2_relay_baton); 
send_dl _prmtv_above(lo _phjl_buff, l2^relay_baton, lo _ph_sdu + 2, 
pdu j>tr~>da!a length - 2, 0x45, lo _ph _j>rmtv j>ath); 

) 


send_m_dl_prmtv_above 


Synopsis 

extern void send_m_dl _prmlv_above(H_buffer_number t l2_relay_baton, l2_data_start_offset, 
size, l2_code, path); 
unsigned short ll_bu//er ^number; 
unsigned short l2_re!ay_baton; 
unsigned short l2_data_start_offset; 
unsigned short size ; 
unsigned char l2_code; 
unsigned char path ; 

Description 

The sendjnjtl j>rmtvjibove monitor routine passes a specified interlayer 
message buffer from Layer 2 to Layer 3 in an OSI monitor primitive. 


InpittS 

See sendjdl _prmtvjabove. Use the monitor variables m_lo _ph_il_buff, 
m_lo _ph_sduj)ffset, and mjo _ph_sdu_size as input. Refer to variable 
m_lo_dl _prmlvj:ode in Table 66-4 for the appropriate primitive code. 


Example 

Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 2 programming block should look like this: 


LAYER: 2 

STATE: send buffer_up 

CONDITIONS: PH_RD_DATA IND 
ACTIONS: 

{ 

_set_maint_buJf_bit(mJo _phjl_bujf, &t2jelay_baton); 

send_m_dl _prmtv_above(mJo _ph_ll_bu/f, !2_retay_baton,m__ lo _ph_sdu_offset t 2, 
m lo _ph_sdu_size - 2, 0x45, m_lo _ph _prnuv _path); 

} 
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send_ph_prmtv_below 


Synapsis 

extern void send jh _prmtv_below(ll_buffer_number, l2_relay_baton, l2_data_start_offset, size, 
l2_code, path); 

unsigned short lt_bu/fernumber; 
unsigned short l2_relay_baton; 
unsigned short l2_data_slart_offset; 
unsigned short size; 
unsigned char l2_code; 
unsigned char path; 


Description 

The send j>h _prmtvJ)elow emulate routine passes a specified interlayer message 
buffer from Layer 2 to Layer 1 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 2 from Layer 3, the variable up_dljl_buff 
may be used to identify the buffer number. If the buffer originated at Layer 2, 
use the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from a call to 
_set_maint_buffj>it . It is used only to pass a received buffer from Layer 2 to 
Layer 1. As soon as Layer 1 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 2, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buffjist_cnt 
routine example at Layer 5.) 

The third parameter is the offset to the Layer 2 list header node in the buffer. 
For a buffer which has been received at Layer 2 from Layer 3, the variable 
upjdl_sdu may be used to indicate the offset. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable ph jtrmlvjype in Table 66-2 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 2 from Layer 3, the variable 
up_dl _prmtv _palh may be used to specify the path number. 
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Example 

A buffer is received at Layer 2 from Layer 3. No text will be inserted at Layer 
2. (For information on inserting text, see _insert_ilj>uff_list_cnt routine.) The 
buffer will be passed to Layer 1, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 

< 

extern volatile unsigned short up_dl_il_bu/f; 
extern volatile unsigned short ,up_dl_sdu; 
unsigned short !2_relay_baton; 

) 

LAVER: 2 

STATE: pass_buHer_down 

CONDITIONS: DL_DATA REQ 
ACTIONS: 

{ 

_set_maint_buff_blt(up_di_ll_buff, <Sd2_retay_baton); 

send _ph _prmtv_below(up_dl H_buff, !2_relay_baton, up dl_sdu, 0, 0x24, 0); 

) 


(D) Layer 3 OSI Routines 

The following routines pass OSI primitives from Layer 3 to either Layer 4 or 
Layer 2. 

send_n_prmtv_above 

Synopsis 

extern void sen d_n _prmtv_above(lI_buf/er_number, !3_relay_baton, l3_data_start_offset, size, 
!3_code, path); 

unsigned short il_buffer_number; 
unsigned short l3_relay_baton; 
unsigned short t3_data_start_offset; 
unsigned short size; 
unsigned char l3_code; 
unsigned char path; 


Description 

The sendji _prmtv_above emulate routine passes a specified interlayer message 
buffer from Layer 3 to Layer 4 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 3 from Layer 2, the variable lo_dl_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
jset_maint_buff_bit. It is used only to pass a received buffer from Layer 3 to 
Layer 4. As soon as Layer 4 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the offset to the Layer 3 service data unit in a received 
buffer. The variable lo_dl_sdu contains the offset to the service data unit when 
the buffer reached Layer 3. The offset must be incremented by the length of 
the Layer 3 header. 


NOTE: In general, do not modify extern variables, such as 
lo_dljsdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after lo_dljsdu has been named in the 
argument of the send routine, add the length of the Layer 3 
header, as in the example below. 


The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure— pdu.datajength. Then subtract the length of the 
Layer 3 header. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo_n _prmtv_code in Table 66-5 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 3 from Layer 2, the variable 
lo_dl _prmtv _path may be used to specify the path number. 

Example 

A buffer is received at Layer 3 from Layer 2. Assuming X.25 protocol, the 
header consists of three bytes. The offset to and size of the service data unit 
will be adjusted by three bytes, a new maintain bit will be set, and the buffer will 
be passed up to Layer 4. 

{ 

struct pdu 

{ 

unsigned char primitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay _baton; 
unsigned short il_buffer_number; 
unsigned char buffer_contents; 
unsigned short data _slart _off set; 
unsigned short datajength; 

}; 
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struct pdu * pdu _ptr; 

extern volatile unsigned short lo_dl _pdu_seg; 
extern volatile const unsigned char lo_dl _prmtv _palh; 
extern volatile unsigned short lo_dl_ll_buff; 
extern volatile unsigned short lo_dl_sdu; 
unsigned short 13 relay baton; 

) 

LAYER: 3 

STATE: send_buffer up 

CONDITIONS: DL DATA IND 
ACTIONS: 

{ 

pdu _ptr = (void *)((long)lo_dl _pdu_seg « 16); 

_set_maint_buffJPlt(lojilJI_buff, &!3_relay_baton ) ; 
sendjt _prmtv_above(lo_dl_ll_buff, !3_relay_baton, lo_dl_sdu + 3, 
pdu _ptr->data_length - 3, 0x65, lo_dl _prmtv _path); 

> 

send_m_n_prmtv_above 

Synopsis 

extern void send_m_n _prmtv_above(UJbuffer_number, l3_relayJt>aton, l3_data_start_offset , 
size, !3_code, path); 
unsigned short ll_buffer_number; 
unsigned short l3_relay_baton; 
unsigned short l3_data_start_offset; 
unsigned short size; 
unsigned char l3_code; 
unsigned char path; 

Description 

The send_m_n _prmlv_above monitor routine passes a specified interlayer 
message buffer from Layer 3 to Layer 4 in an OSI monitor primitive. 

In p ut s 

See sendji _prmtv_above. Use the monitor variables mJojilJl_buff, 
m_lo_dl_sdu_offset, and m_lo_dl_sdu_size as input. Refer to variable 
m_lo_n _prmtv_code in Table 66-5 for the appropriate primitive code. 

Example 

Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 3 programming block should look like this: 

LAYER: 3 

STATE: send_buffer_up 

CONDITIONS: DL_RD_DATA IND 
ACTIONS: 

< 

_set_matntJbuff_bit(m_lo_dljl_buff, &l3_relay_baton); 

send m n _prmtv^above(m_lo_dl_il_buff, l3_relay_baton, mJojdljsdujoffsel + 3, 
mjo dl sdu_slze - 3, 0x65, m_lo_dl _prmtv _path); 

) 
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send_dl_prmtv_below 


Synopsis 

extern void send_dl _prmtv_below(ll_buffer_number, l3_reiay_baton, l3_data_start_offset, site, 
l3_code, path); 

unsigned short U_bu/fer_number; 
unsigned short !3_retay_baton; 
unsigned short !3_data_start_offset; 
unsigned short size; 
unsigned char !3_code; 
unsigned char path; 


Description 

The sendjdl _prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 3 to Layer 2 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 3 from Layer 4, the variable up_n_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 3, use 
the buffer-number variable named in the _ge(Jl_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from a call to 
_setjnaint_buff_bit. It is used only to pass a received buffer from Layer 3 to 
Layer 2. As soon as Layer 2 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 3, use the maintain bit 
variable named in the _getjljnsgJ>uff routine. (See Jnsert_il_buffJist_cnt 
routine example at Layer 5.) 

The third parameter is the offset to the Layer 3 list header node in the buffer. 
For a buffer which has been received at Layer 3 from Layer 4, the variable 
up_n_sdu may be used to indicate the offset. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_dl _prmtv_code in Table 66-3 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 3 from Layer 4, the variable 
up_n _prmtv jpath may be used to specify the path number. 
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Exa mple 

A buffer is received at Layer 3 from Layer 4. No text will be inserted at Layer 
3. (For information on inserting text, see _insertjl_buffjist_cnt routine.) The 
buffer will be passed to Layer 2, requiring a new maintain bit to be set. If 
values are entered for the code and path, these variables need not be declared. 

{ 

extern volatile unsigned short up_n_ll_buff; 
extern volatile unsigned short up_n_sdu; 
unsigned short I3_relay baton; 

) 

LAYER: 3 

STATE: pa$s_buffer_down 
CONDITIONS: N_DATA REQ 
ACTIONS; 

< 

jsetjn a in tj)uff_bit (upn_il_buff, & I3_relay_ba ton); 

send dl _prmtv_below(upn_il buff, l3_relay_baton, up n sdu, 0, 0x44, 0); 

) 


(E) Layer 4 OSI Routines 

The following routines pass OSI primitives from Layer 4 to either Layer 5 or 
Layer 3. 


send_t_prmtv_above 

extern void send_t _prmtv_above(il_buffer_number, l4_relay_balon, l4_data_slart_offset, size, 
!4_code, path); 

unsigned short il_buffer_number; 
unsigned short t4^_relay_baton; 
unsigned short l4_dala_start_offset; 
unsigned short size ; 
unsigned char !4_code; 
unsigned char path; 


Description 

The sendj j>rmtv_above emulate routine passes a specified interlayer message 
buffer from Layer 4 to Layer 5 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 4 from Layer 3, the variable lo_n_il_buff may 
be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_sel _maint Jmff _bit . It is used only to pass a received buffer from Layer 4 to 
Layer 5. As soon as Layer 5 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the offset to the Layer 4 service data unit in a received 
buffer. The variable lo_n_sdu contains the offset to the service data unit when 
the buffer reached Layer 4. The offset must be incremented by the length of 
the Layer 4 header, if any. 

NOTE: In general, do not modify extern variables, such as 
lo_n_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after lo_n__sdu has been named in the 
argument of the send routine, add the length of the Layer 4 
header, if any. 

The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure— pdu.datajength. Then subtract the length of the 
Layer 4 header, if any. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable loj _prmtv_code in Table 66-6 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 4 from Layer 3, the variable 
loji _prmtv _path may be used to specify the path number. 

Example 

A buffer is received at Layer 4 from Layer 3. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 5. 

{ 

struct pdu 

{ 

unsigned char primitive _code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relaybaton; 
unsigned short it_buffer_number; 
unsigned char buffer _conlents; 
unsigned short data_start_offset; 
unsigned short datajength ; 

); 

struct pdu * pdu _plr; 

extern volatile unsigned short lo_n _pdu_seg; 
extern volatile const unsigned char Io n _prmtv _path; 
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extern volatile unsigned short lo_n_ll_buJf; 
extern volatile unsigned short lo_n_sdu; 
unsigned short !4_relay_baton; 

} 

LAYER: 4 

STATE: eend_buffer_up 

CONDITIONS: N ~DATA IND 
ACTIONS: 

{ 

pdu _ptr = (void , )((long)lo_n _pdu_seg « 16); 

_se tjn ainljbu/fjbl t (lo_n_il_buff, it t4_relay_baton ) ; 

sendj_prmtv_above(lo_njl_buff, !4_retay_baton, lo_n_sdu,pdu _ptr->data_length, 
0x85, lo_n _prmtv _path ); 

) 

send_m_t_prmtv_above 

Synopsis 

extern void send_m_t_prmtv_above(ll_buffer_number, t4_relay_baton, l4_data_starl_offsel, 
size, l4_code, path); 
unsigned short il_buffer_number; 
unsigned short l4_relay_baton; 
unsigned short l4_data_starl_offset; 
unsigned short size; 
unsigned char !4_code; 
unsigned char path; 

Description 

The send_m_t _prmtv_above monitor routine passes a specified interlayer message 
buffer from Layer 4 to Layer 5 in an OSI monitor primitive. 

In put s 

See send_t_prnuv_above. Use the monitor variables m_lo_n_il_buff, 
m_lo_njsdu_offsel, and mJo_n_sdu_size as input. Refer to variable 
m_loj _prmtv_code in Table 66-6 for the appropriate primitive code. 

Example 

Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 4 programming block should look like this: 

LAYER: 4 

STATE: send_buffer_up 

CONDITIONS: N_RD_DATA IND 
ACTIONS: 

{ 

_set_mainl_buff_bit(m_lo_nJI_buff, &!4_relay_baton); 

send_m_t_prmtv_above(m_lo_nJH_buff, l4_relay_baton, lo_n_jdu_offset , 
m_lo_n_sdu_size, 0x85, m_lo_n _prmtv _path); 
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( 


send_n_prmtv_below 


Synopsis 

extern void send_n _prmtv_below(ll_buffer__number, l4_relay_baton, l4_data_starl_offset, size, 
!4_code, path); 

unsigned short li_buffer_number; 
unsigned short i4~relay_baton; 
unsigned short l4_data_starl_offset; 
unsigned short size; 
unsigned char !4_code; 
unsigned char path; 


Description 

The sendjx _prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 4 to Layer 3 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 4 from Layer 5, the variable up_l_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 4, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_il_buff_list_cnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 4 to 
Layer 3. As soon as Layer 3 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 4, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See JnsertJl_buff_list_cnt 
routine example at Layer 5.) 

The third parameter is the offset to the Layer 4 list header node in the buffer. 
For a buffer which has been received at Layer 4 from Layer 5, the variable 
up_t_sdu may be used to indicate the offset. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_n _prmtv_code in Table 66-4 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 4 from Layer 5, the variable 
up_t _prmiv _path may be used to specify the path number. 
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Example 

A buffer is received at Layer 4 from Layer 5. No text will be inserted at Layer 
4. (For information on inserting text, see Jnseri JlJ>uff_list _cnt routine.) The 
buffer will be passed to Layer 3, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 

{ 

extern volatile unsigned short up_t_ll_buff; 
extern volatile unsigned short up_t_sdu; 
unsigned short !4_relay_baton; 

) 

LAYER: 4 

STATE: pass buffer_down 
CONDITIONS: T_DATA REQ 
ACTIONS: 

{ 

_set_maint_buff_blt( up_t_il_buff, Jd4_relay_baton ) ; 

send_n _prmtv betow(up t_il_bu/f, I4_relay baton, up_t_sdu, 0, 0x64, 0); 

) 

(F) Layer 5 OSI Routines 

The following routines pass OSI primitives from Layer 5 to either Layer 6 or 
Layer 4. 


send_s_prmtv_above 

Sy no psis 

extern void send_s _prmtvjabove(il_buffer_number, l5_relay_baton, IS_data_start_offset, size, 
ISjcode, path); 

unsigned short il_buffer_number; 
unsigned short IS_relay_baton; 
unsigned short l5_data_start_offset; 
unsigned short size; 
unsigned char !5_code; 
unsigned char path; 

Description , 

The send_s _prnUv_above emulate routine passes a specified inter-layer message 
buffer from Layer 5 to Layer 6 in an OSI primitive. 


Inputs 

The first parameter is the inter-layer buffer number to be sent. For a buffer 
which has been received at Layer 5 from Layer 4, the variable may 

be used to identify the buffer number. 
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The second parameter is the returned maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 5 to 
Layer 6. As soon as Layer 6 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the offset to the Layer 5 service data unit in a received 
buffer. The variable lo_t_sdu contains the offset to the service data unit when 
the buffer reached Layer 5. The offset must be incremented by the length of 
the Layer 5 header, if any. 

NOTE: In general, do not modify extern variables, such as 
Io_t_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after loj_sdu has been named in the argument 
of the send routine, add the length of the Layer 5 header, if any. 

The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure— pdu. data _len$th. Then subtract the length of the 
Layer 5 header, if any. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo^s _prmtvj:ode in Table 66-7 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 5 from Layer 4, the variable 
loj _prmtv _path may be used to specify the path number. 

Examnle 

A buffer is received at Layer 5 from Layer 4. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 6. 

{ 

struct pdu 

{ 

unsigned char primitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay_balon; 
unsigned short il_buffer_number; 
unsigned char buffer_contents; 
unsigned short data_start_offset; 
unsigned short data_length; 

); 

struct pdu * pdu _ptr; 

extern volatile unsigned short lo_t _pdu_seg; 
extern volatile const unsigned char lo_t_prmtv _path; 
extern volatile unsigned short lo_t_il _buff; 
extern volatile unsigned short lo_t_sdu; 
unsigned short IS_relay_baton; 

) 
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LAYER: 5 

STATE: send_buffer_up 

CONDITIONS: T_DATA IND 
ACTIONS: 

{ 

pdu _ptr = (void ’)((long)lo_t_pdu_seg « 16); 

_set_malnt_buff_bit(lo_t_ll~buff, &15 _retay_baton) ; 

send_s _prmtv_above(lo^t_il_buff, IS_retay_baton, lo_l_sdu, pdu _ptr->d ata Jength , 
OxaS, io_t_prmtv _path); 

) 


send_m_s_prmtv_above 


SyUOPSiS 

extern void send_m_s _prmtv_above(ll_buffer_number, t$_relay_baton, I5_data_start_pffset, 
size, l5_code, path); 
unsigned short ll_buffer_number; 
unsigned short l5_relay_baton; 
unsigned short l5_data_start_offset; 
unsigned short size; 
unsigned char lS_code; 
unsigned char path; 


Description 

The send_m_s _prmtv_above monitor routine passes a specified inter-layer 
message buffer from Layer 5 to Layer 6 in an OSI monitor primitive. 


Inputs 

See send_s_prmtv_above. Use the monitor mJo_t_ii_buff, m_lo_t_sdu_offset, 
and m_lo_(_sdu_size variables as input. Refer to variable mJo_s _prmtvjcode in 
Table 66-7 for the appropriate primitive code. 


Example 

Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 5 programming block should look like this: 


LAYER: 5 

STATE: send_buffer_up 

CONDITIONS: T_RD_C>ATA ]nd 
ACTIONS: 

< 

jsetjnaint_buff_blt(m_lo_tJl_buJf, &IS_relay_baton); 
send_m_s _prmtv_above(mJio_tJil_buff, l5_relay_baton,m_ lo_t_sdu_offsel, 
m_lo_l_sdu_size, OxaS, m loj_prmtv _path); 

> 
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send_t_prmtv_below 

Synopsis 

extern void send _t_prmtv_below(ll_bu//er_number, lS_relay_baton, t5_data_start_offset, size, 

!5_code, path); 

unsigned short il_buffer_number; 
unsigned short l5_relay_baton; 
unsigned short lS_data_start_offsel; 
unsigned short size; 
unsigned char ISjcode; 
unsigned char path; 

D e scri ptio n 

The sendj _prmtv_below emulate routine passes a specified inter-layer message 
buffer from Layer 5 to Layer 4 in an OSI primitive. 

Inputs 

The first parameter is the inter-layer buffer number to be sent. For a buffer 
which has been received at Layer 5 from Layer 6, the variable up_s_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 5, use ( 

the buffer-number variable named in the _jet_il_msg_buff routine. (See 
_insert_il_buff_listjcnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from a call to 
__set_main(_buff_bit . It is used only to pass a received buffer from Layer 5 to 
Layer 4. As soon as Layer 4 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 5, use the maintain bit 
variable named in the _&etjl_msgjbujf routine. (See Jnsert _il jbuff _list _cnt 
routine example at Layer 5.) 

The third parameter is the offset to the Layer 5 list header node in the buffer. 

For a buffer which has been received at Layer 5 from Layer 6, the variable 
up_s_sdu may be used to indicate the offset. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_t _prmtv_code in Table 66-5 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 

a buffer which has been received at Layer 5 from Layer 6, the variable 

up_s _prmtv _path may be used to specify the path number. V 
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Example 

A buffer is received at Layer 5 from Layer 6, No text will be inserted at Layer 
5. (For information on inserting text, see JnsertJl_buffJist_cnt routine.) The 
buffer will be passed to Layer 4, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 

1 

extern volatile unsigned short upjsJUJbuJf; 
extern volatile unsigned short up_s_sdu: 
unsigned short IS_relay_baton; 

) 

LAYER: 5 

STATE: pass_buffer_down 
CONDITIONS: S_DATA REQ 
ACTIONS: 

{ 

_set_ma int_bu/f_bi t ( up_s_il_buff, &lS_reiayJbaton ) ; 

send t _prmtv below (up_s it buff, IS_relay baton, up_s_sdu, 0, 0x84, 0); 

) 

(G) Layer 6 OSI Routines 

The following routines pass OSI primitives from Layer 6 to either Layer 7 or 
Layer 5. 

send_p_prmtv_ahove 


Synopsis 

extern void send _p _prmtv_above(ii_buffer_number, l6_relay_baton, l6_dala_start_offset, size, 
l6_code, path); 

unsigned short il_bu/fer_number; 
unsigned short l6_relay_baton; 
unsigned short l6_data_start_offset; 
unsigned short size; 
unsigned char !6_code; 
unsigned char path; 

Description 

The send _p _prmlv_above emulate routine passes a specified interlayer message 
buffer from Layer 6 to Layer 7 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 6 from Layer 5, the variable lo_s_il_buff may 
be used to identify the buffer number. 


JUL ’90 


66-63 




INTERVIEW 7000 Series Advanced Programming: ATLC-1 07-951 -108 


The second parameter is the relumed maintain bit from a call to 
_set_maint_buff_bit. It is used only to pass a received buffer from Layer 6 to 
Layer 7. As soon as Layer 7 processing on the buffer is completed, the bit is 
automatically freed. 

The third parameter is the offset to the Layer 6 service data unit in a received 
buffer. The variable lo_s_sdu contains the offset to the service data unit when 
the buffer reached Layer 6. The offset must be incremented by the length of 
the Layer 6 header, if any. 

NOTE: In general, do not modify extern variables, such as 
lo_s_sdu, which may be updated by other processes. Name 
another variable, assign it the same value, and then increment 
that variable. Or, after lo_s_sdu has been named in the 
argument of the send routine, add the length of the Layer 6 
header, if any. 

The fourth parameter is the length of the data in the buffer. Use the length 
indicated in the pdu structure— pdu.datajength. Then subtract the length of the 
Layer 6 header, if any. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable lo _p _j>rmtv_code in Table 66-8 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 6 from Layer 5, the variable 
lo_s _prmtv jjath may be used to specify the path number. 

Ex am ple 

A buffer is received at Layer 6 from Layer 5. The offset to and size of the 
service data unit will be adjusted if needed, a new maintain bit will be set, and 
the buffer will be passed up to Layer 7. 

{ 

struct pdu 

< 

unsigned char prlmitive_code; 
unsigned char path; 
unsigned long parameter; 
unsigned short relay _baton; 
unsigned short U_buffer_number; 
unsigned char buf/er_contents; 
unsigned short data _start_off set; 
unsigned short datajength; 

}; 

struct pdu * pdu jptr; 

extern volatile unsigned short lo_s _pdu_seg; 
extern volatile const unsigned char lo_s _prmtv j>ath; 
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extern volatile unsigned short lo_sJI_bu/f; 
extern volatile unsigned short lo_s_sdu; 
unsigned short l6_relay_baton ; 

} 

LAYER: 6 

STATE: send_buffer_up 

CONDITIONS: S_DATA IND 
ACTIONS: 

{ 

pdu _ptr = ( void *) C (tong)lo_s _pduseg « 16); 

_set_malnt_buff_bit(lo_sjl_buff, <St 1 6_rel ayjbaton); 

send j _prmtv_above(lo_s_il_buff, l6_relay_baton, lo_s_sdu, pdu _ptr->datajength, 
OxcS, lo_s_prmlv _path ) ; 

) 

send_m_p_prmtv_above 

Synopsis 

extern void send^m _p _prmtv_above(il_buffer_number, l6_relayJbaton, l6_data_start_offset, 
size, !6_code, path); 
unsigned short il_buffer_number; 
unsigned short !6jrelay_baton; 
unsigned short l6_data_start_offset; 
unsigned short size; 
unsigned char l6_code; 
unsigned char path; 

Description 

The send_m j> _prmtv_above monitor routine passes a specified interlayer 
message buffer from Layer 6 to Layer 7 in an OSI monitor primitive. 

In puts 

See send _p_prmtv_above. Lise the monitor variables m_lo_sJl_buff, 
m_lo_s_sdujoffset, and m_lo_s^sdu_size as input. Refer to variable 
mjo _p _prmtv_code in Table 66-8 for the appropriate primitive code. 

Example 

Make the appropriate variable declarations. For a condition monitoring RD data 
primitives, the Layer 6 programming block should look like this: 

LAYER: 6 

STATE: send_buffer_up 

CONDITIONS: S_RD_DATA IND 
ACTIONS: 

{ 

_se t_m ain t_buff_bit(mJo_s_ll_buff, & !6_relay_balon ) ; 

sendjn _p _prmtv_above(mlojJl_buff, l6_relay_baton,m_ lo_s_sdu_offset, 
mjo s sdu_size, 0xc5, mjo _s_prm tv _path); 

) 
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send_s_prmtv_below 


Synopsis 

extern void send_s_prmtv_below(il_buJfer_number, l6_relay_baton , l6_dala_slart_offset, size, 
!6_code, path); 

unsigned short H_buffer_number; 
unsigned short l6_relay_baton; 
unsigned short l6_data_start_offset; 
unsigned short size; 
unsigned char !6_code; 
unsigned char path; 

Description 

The send_s _prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 6 to Layer 5 in an OSI primitive. 

Inputs 

The first parameter is the interlayer buffer number to be sent. For a buffer 
which has been received at Layer 6 from Layer 7, the variable up J3_il_buff may 
be used to identify the buffer number. If the buffer originated at Layer 6, use 
the buffer-number variable named in the _get_il_msg_buff routine. (See 
_insert_iljbuff_lisl_cnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from a call to 
jsel_maint_buff_bit. It is used only to pass a received buffer from Layer 6 to 
Layer 5. As soon as Layer 5 processing on the buffer is completed, the bit is 
automatically freed. If the buffer originated at Layer 6, use the maintain bit 
variable named in the _get_il_msg_buff routine. (See _insert_il_buff_list_cnt 
routine example at Layer 5.) 

The third parameter is the offset to the Layer 6 list header node in the buffer. 
For a buffer which has been received at Layer 6 from Layer 7, the variable 
up _p_sdu may be used to indicate the offset. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up_s _prmtv_code in Table 66-6 for the 
appropriate primitive code. 

The sixth parameter is the path number along which the buffer will be sent. For 
a buffer which has been received at Layer 6 from Layer 7, the variable 
up _p _prmtv _path may be used to specify the path number. 
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Example 

A buffer is received at Layer 6 from Layer 7. No text will be inserted at Layer 
6. (For information on inserting text, see _insert_il_buff_listjcnt routine.) The 
buffer will be passed to Layer 5, requiring a new maintain bit to be set. If 
values are entered for the code and path, variables for code and path need not 
be declared. 

< 

extern volatile unsigned short up _pjl_bu/f; 
extern volatile unsigned short up _p_sdu; 
unsigned short I6_relay baton; 

) 

LAYER: 6 

STATE: pass buffer down 
CONDITIONS: P_DAT A REQ 
ACTIONS: 

{ 

_set_maint'_buff_bit(up _p_il_buff, &l6_reiay_baton) ; 

send s j>rmtv_below(up_p_ll_buff, l6_relay_baton, up_p_sdu, 0, 0xa4, 0); 

) 

(H) Layer 7 OSI Routines 
send_p_prmtv_below 

Synopsis 

extern void send _p_prmlv_betow(ll_buffer_number, relay Jbaton, data _start_o/J set, size, code, 
path); 

unsigned short ii_buffer_number; 
unsigned short relay _baton; 
unsigned short data _start_off set; 
unsigned short size; 
unsigned char code; 
unsigned char path; 

Description 

The send_p _prmtv_below emulate routine passes a specified interlayer message 
buffer from Layer 7 to Layer 6 in an OSI primitive. 


Inputs 

The first parameter is the interlayer buffer number to be sent. Use the 
buffer-number variable named in the jget_il_msg_buff routine. (See 
Jnsert_il_buffJist_cnt routine example at Layer 5.) 

The second parameter is the returned maintain bit from the call to 
_get_il_msg_buff. 
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The third parameter is the returned offset (from a call to _start il_buffjist) to 
the Layer 7 list header node in the buffer. 

The fourth parameter is the size of the data in the buffer. It will always be set 
to zero since the data length is unknown in a primitive being passed down the 
layers. 

The fifth parameter is the code specifying the type of primitive in which the 
buffer will be sent. Refer to variable up _p _prmtv_code in Table 66-7 for the 
appropriate code. 

The sixth parameter is the path number along which the buffer will be sent. 

Example 

A buffer is obtained at Layer 7. The buffer will be passed to Layer 6, without 
any data inserted. (For information on inserting text, see Jnsertjl_buffJist_cnt 
routine.) If values are entered for the code and path, variables for code and 
path need not be declared. 

{ 

unsigned short iljbuffer_number; 
unsigned short data_slart_o/fsel; 
unsigned short relay_baton; 

} 

LAYER; 7 

STATE; passjjuffer down 

CONDITIONS; KEYBOARD “ " 

ACTIONS: 

< 

_get_!l_msg_buff(&il_buffer_number, &retay_baton ); 

_startjl_buff_list (il_buffer_number, &dala_starl_offset ); 

send _p _prmtv below (il_buffer_number, relayjbaton, data_start offset, 0, 0xc4, 0 }; 

> 


( 
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The PRINTER port is a serial interface through which the programmer may direct output from 
the INTERVIEW to a printer. The printer port is located at the rear of the INTERVIEW 
between the REMOTE RS-232 and AUXILIARY ports. 


NOTE: Before directing output to the printer port, configure the 
Printer Setup menu as explained in Section 15.2. 


Each spreadsheet PRINT action or call to one of the C print routines causes output to be 
added to a queue of unprinted text in the print buffer. If not doing so already, the print 
server also begins to poll the print buffer for text to print. As long as there is unprinted text 
in the buffer, the print server polls the buffer, removes text, and sends it to the printer port 
of the INTERVIEW. Use the _print_bu//er structure to monitor the flow of text in and out 
of the print buffer. 

Use any of the four C print routines explained in this section to add text to the print buffer. 
Three of them— printc, print /, and prints— are similar to the displayc, display /, and displays 
routines which direct output to the Display Window. See Section 64.3(C). With the 
set _print Jieader routine, you determine the heading which will appear at the top of each 
printed page. One other routine, sprint /, writes output to a string. The string can then be 
referenced in subsequent calls to printf. (You may also use the string named in sprintf in 
calls to display /, trace/, or /print/.) 

67.1 Structures 

Refer to Table 67-1 for the structure of the print buffer. Compare j)rintJ>u//er.in 
with _print_bu//er.out to determine whether or not the print buffer has emptied. 
When the values of these two variables are equal, the buffer is empty. 


NOTE: Consider the variables in the _print_bu//er structure 
read-only variables. In general, do not modify extern structures 
or variables which may be updated by other processes. 


At times, processes may add transactions to the print buffer more quickly than the 
print server takes them out. If a process cannot add to the buffer without overwriting 
unprinted text, a buffer overrun occurs. When your INTERVIEW is configured for 
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data playback, you can minimize print-buffer overruns by periodically suspending 
playback and allowing the print server to empty the buffer. In judging how often to 
suspend playback, keep in mind the following points: 1) In general, the more 
conditions a program has that trigger print actions, the more frequently playback 
should be suspended. 2) When planning to print Run-mode buffers, remember that 
the faster the playback speed, the quicker the print buffer fills. 


Table 67-1 
Print Structures 


Type 

Variable 

Value (hex/decimal) 

Meaning 

Structure Name: print buffer 


Structure of the print buffer. Declared as type 
struct. 

unsigned short 

In 

a-207/10-BT99 

offset Into the print buffer (from the physical 
beginning of the buffer) to the location where 
next transaction text will be added. Advances 
with each spreadsheet PRINT aotion or oall to a 
C print routine. When In equals out, the print 
buffer Is empty. 

unsigned short 

out 

a-207 110-8199 

offset Into the print buffer (from the physical 
beginning of the buffer) to the last transaction 
text printed from the buffer. Advances each 
time text Is actually sent out the printer port of 
the INTERVIEW. When out equals In, the print 
buffer Is empty. 

unsigned short 

buffer_end 

209/8201 

offset to the physical end of the print 
buffer— l.e., to the end of the array named 
buffer (see below) 

unsigned short 

lock 


when process Is printing, locks out other 
processes from accessing the print buffer 

char 

polling 

0 

non-zero 

print server Is not polling 

print server Is polling print buffer for text to print 

char 

overrun 

0 

non-zero 

print buffer Is not In overrun state 
print buffer Is In overrun state— l.e., a process 
attempting to add text to the print buffer can’t 
because unprlnted text In the buffer would be 
overwritten. Following message will appear on 
printout: “print buffer overrun has occurred. " 

char 

buffer [8192] 


array of text transactions 

Structure Name: Drlnt buffer 


An Instance of the prlnt_bu/ler structure, 
declared as type extern struct prlnt_bu(ler. Use 
the variables contained In this structure to 
monitor flow of text In and out of the print buffer. 
Reference structure variables as follows: 
_prlnt_bulfer.ln. 
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The following example shows how you might use a TIMEOUT condition to check the 
print buffer periodically. Each time the timeout expires, the program determines 
whether or not the buffer is half full. If so, playback is suspended. If the buffer is 
only one-quarter full, playback is resumed. (Other conditions in the program, not 
illustrated here, would cause print actions to send output to the print buffer.) 

{ 

ftdefine PRINT_BUFFER_SZ 8192 

ftdefine STOP_P01NT ( PRlNT_BUFFER_SZ/2 ) 

If define START _POI NT (PRINT_B UFFER_SZ/4) 

} 

LAYER; 1 

{ 

struct print _buffer 

{ 

unsigned short In; 
unsigned short out; 
unsigned short buffer_end ; 
unsigned short lock; 
char polling; 
char overrun; 

); 

extern struct print _buffer __prtnt_buffer; 
int crnt_buffer_sz; 

) 

STATE: check_prlnt_buffer 

CONDITIONS: ENTER_STATE 
ACTIONS: TIMEOUT ck_bu(fer RESTART 0.01 
CONDITIONS: TIMEOUT ck_buffer 
ACTIONS: 

{ 

crnt_buffer_sz = ((_print_buffer. in + PR1NT_BUFFER_SZ) - _print_buffer.out) % 
PRINT_BUFFER_SZ; 
if (cm tbuffer _sz > STOP_POINT) 
suspend j-crd j>lay(); 
else if(crnt_buffer_sz < START_POINT) 
start rcrd _play(); 

} 

TIMEOUT ck_buffer RESTART 0.01 


67.2 Variables 

There are no variables associated exclusively with print functions. 
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67.3 Routines 

printc 

Synopsis 

extern void printc(character); 
const char character; 

Description 

The printc routine outputs a single ASCII character to the print buffer for printing, 
converting the value provided as the argument into its ASCII equivalent. Decimal 
and octal values are converted to hexadecimal format before the ASCII equivalent is 
sought. 

Inputs 

The only parameter is a numerical value. The value may be given as a hexadecimal, 
octal, or decimal constant: as an alphanumeric constant inside of single quotes; or as 
a variable. A hexadecimal value must be preceded by the prefix Ox or OX; an octal 
value must be preceded by the prefix 0. If no prefix appears before the input, the 
number is assumed to be decimal. Valid numeric entries are 00 to 127, decimal. An 
alphanumeric character placed between single quotes will be output as is to the 
printer. 

Example 

The printc entries on the left output the printed character given on the right: 


printc('a’); a 

printc(6S); A 

printc(0x65); e 

printc(065); 5 


printf 

Synopsis 

extern int printf (format j>tr, . . . ); 
const char * format _ptr; 

Description 

The printf routine writes output to the print buffer for printing, under control of the 
string pointed to by format _ptr that specifies how subsequent arguments are converted 
for output. If there are insufficient arguments for the format, the behavior is { 
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undefined. If the format is exhausted while arguments remain, the excess arguments 
are evaluated but otherwise ignored. The print f routine returns when the end of the 
format string is encountered. 

Inputs 

The format is composed of zero or more directives: ordinary characters (not %), 
which are copied unchanged to the output stream; and conversion specifications, each 
of which results in fetching zero or more subsequent arguments. Each conversion 
specification is introduced by the character %. After the %, the following appear in 
sequence: 

• Zero or more flags that modify the meaning of the conversion specification. 

The flag characters and their meanings are: 

The result of the conversion will be left-justified within the field. 

+ The result of a signed conversion will always begin with a plus or minus 
sign. 

space If the first character of a signed conversion is not a sign, a space will be 
prepended to the result. If the space and + flags both appear, the space 
flag will be ignored. 

# The result is to be converted to an “alternate form." For d, i, u, c, and 
s conversions, the flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a zero. For x (or X) 
conversion, a nonzero result will have Ox (or OX) prepended to it. 

• An optional decimal integer specifying a minimum field width. If the converted 
value has fewer characters than the field width, it will be padded on the left (or 
right, if the left adjustment flag, described above, has been given) to the field 
width. The padding is with spaces unless the field width integer starts with a 
zero, in which case the padding is with zeros. 

• An optional precision that gives the minimum number of digits to appear for the 
d, i, o, u, x, and X conversions, or the maximum number of characters to be 
written from an array in an s conversion. The precision takes the form of a 
period (.) followed by an optional decimal integer; if the integer is omitted, it is 
treated as zero. The amount of padding specified by the precision overrides that 
specified by the field width. 

• An optional h specifying that a following d, i, o, u, x, or X conversion specifier 
applies to a short int or unsigned short int argument (the argument will have 
been promoted according to the integral promotions, and its value shall be 
converted to short int or unsigned short int before printing); or an optional 1 
specifying that a following d, i, o, u, x, or X conversion specifier applies to a 
long int or unsigned long int argument. If an h or 1 appears with any other 
conversion specifier, it is ignored. 
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• A character that specifies the type of conversion to be applied. (Special AR 

extensions have been added.) The conversion specifiers and their meanings are: 

d, i, o, u, x, X 

The int argument is converted to signed decimal (d or i), unsigned octal 
(o), unsigned decimal (u), or unsigned hexadecimal notation (x or X); the 
letters abcdef are used for x conversion and the letters ABCDEF for X 
conversion. The precision specifies the minimum number of digits to 
appear; if the value being converted can be represented in fewer digits, it 
will be expanded with leading zeros. The default precision is 1. The 
result of converting a zero value with a precision of zero is no characters. 

c The int argument is converted to an unsigned char, and the resulting 
character is written. 

s The argument shall be a pointer to a null-terminated array of 8-bit chars. 
Characters from the string are printed up to (but not including) the 
terminating null character: if the precision is specified, no more than that 
many characters are printed. The string may be an array into which 
output was written via the sprintf routine. 

p The argument shall be a pointer to void. The value of the pointer is 
converted to a sequence of printable characters, in this format: 

0000:0000. There are always exactly 4 digits to the right of the colon. 

The number of digits to the left of the colon is determined by the 
pointer’s value and the precision specified. Use this conversion to print 
80286 memory addresses. The segment number will appear to the left of 
the colon and the offset to the right. 

% A % is written. No argument is converted. 

\n Writes hexadecimal OD OA, the ASCII carriage-return and linefeed 
characters. No argument is converted. 

If a conversion specification is invalid, the behavior is undefined. 

If any argument is or points to an aggregate (except for an array of characters using 
%s conversion or any pointer using %p conversion), the behavior is undefined. 

In no case does a nonexistent or small field width cause truncation of a field; if the 
result of a conversion is wider than the field width, the field is expanded to contain 
the conversion result. 

Returns 

The print / routine returns the number of characters output. 

Ex ample 

To print a date and time in the form "Sunday, July 3, 10:02,” where weekday and 
month are pointers to strings: 
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LAYER: 1 

< 

unsigned char date time [100}; 
unsigned char weekday [10]; 
unsigned char month [10J; 
unsigned short day; 
unsigned char hour; 
unsigned char min; 

) 

STATE: output_to_prlnter 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: 

< 

prinlf( " %s , %s %d, %.2d:%.2d\n " , weekday, month, day, hour, min); 

) 

sprintf 

Synopsis 

extern int sprintf (string_ptr, format _ptr ); 
unsigned char string (128); 
const char * format _ptr; 

D e scri p tion 

The sprintf routine is similar to the print f routine, except that sprintf writes output to 
a string, while printf writes output directly to the print buffer for printing. The sprintf 
routine is useful for writing formatted output to a display, printer, or file. 

The output is under control of the string pointed to by format _ptr that specifies how 
subsequent arguments are converted for output. If there are insufficient arguments 
for the format, the behavior is undefined. If the format is exhausted while arguments 
remain, the excess arguments are evaluated but otherwise ignored. The sprintf 
routine returns when the end of the format string is encountered. 

Inputs 

The first parameter is a pointer to the array to which output will be written. 

For the second parameter, see printf routine. 

Returns 

This routine returns the number of characters written into the array, not counting the 
added null terminating character. 

Example 

Refer again to the sample program for the displayf routine in Section 64.3(C). This 
lime you also want to send the output to a printer. By using the sprintf routine, you 
only have to enter the format string once. 
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LAYER: 1 

{ 

unsigned char datejime 1100]; 
unsigned char weekday [10]; 
unsigned char month [10]; 
unsigned short day; 
unsigned char hour; 
unsigned char min; 

} 

STATE : output_to_dlsplay_wlndow_and_prlnter 
CONDITIONS: KEYBOARD “ " 

ACTIONS: 

sprintf(date_iime, "%s, %s %d, %.2d : %.2d\n", weekday, month, day, hour, 
min); 

dlsplayf(“%s", datejime); 
printf(“%s" , datejime ); 

) 

set_print_header 

Synopsis 

extern int set _prinlJieader(format j>tr ); 

const char * format j>tr; ^ 

Description 

This routine writes output to the print buffer, to be printed after each form feed, 
under control of the string pointed to by format _ptr. Paging is done automatically by 
the INTERVIEW, The set _print Jteader routine returns when the end of the format 
string is encountered. 

Inputs 

The format is composed of zero or more ordinary characters. Octal or hexadecimal 
values also may be input, with octal preceded by \ and hex by \x. Pad each value 
to three integers with leading zeroes. 

The status information shown above the prompt line on the display screens of the 
INTERVIEW can be sent to a printer with the following inputs: 

ttd date (mm/dd/yy) 

tit time (hh:mm) 

tip page (not shown on the display screens) 

tib block number 

titi ti 

Re t u rn s 

The set _print_header routine returns the length of the header (0-255), or a -1 if the 
header exceeds the buffer size. ( 
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Example 

If you want the date, time, and page number to appear in the heading on each page 
sent to a printer, enter the following: 

LAYER: 2 

STATE: header 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set _print_header("ttm ttd Hi Up ##M\n u ); 

} 

The printer output will look like this: 

»H 09/01/89 09:30 page : 1 Htt 


HH 09/01/89 09:31 


page : 2 »tt 


reset_print_page 

Synopsis 

extern int reset _prlnt _page( ); 

Pescription 

The reset _print _page routine resets the INTERVIEW'S automatic page numbering for 
printer output to 1. 

Returns 

If the page number is successfully reset, the routine returns zero. If the print buffer 
is overrun, it returns -1. 

Example 

In the following example, a header with page numbering is assigned to printed output. 
(See set _printjxeader routine above.) Elsewhere in the program (not shown) the 
programmer has designated text to be printed. When the user presses the spacebar, 
a new header will appear on the next page output to the printer. That output will 
begin again with page 1. 
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LAYER: 1 

STATE: prlnt_outpul 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set _print_header(“ttd #t First Header ttp\n ”); 

} 

CONDITIONS: KEYBOARD “ " 

ACTIONS: 

{ 

set _prlnt_header(“#d ttt New Header ttp\n"); 

reset _print _page(); 

) 


prints 

Synopsis 

extern void prints(string_ptr ); 
const char ' stringjtr; 

Description 

The prints routine is similar to the displays routines, except that prints writes output 
to the print buffer for printing while displays writes output to the Display Window. 
The output is under control of the string pointed to by the argument. The prints 
routine returns when the end of the string is encountered. The softkey equivalent of 
this routine is the PRINT PROMPT action on the Protocol Spreadsheet. A PRINT 
PROMPT action automatically time-stamps the output. Although prints does not, you 
can create your own time or date stamp with set _print_header. 

In puts 

The input is a pointer to a string composed of zero or more ordinary characters. 

The newline nonliteral sequence “\n" writes hex OD OA (ASCII S»V) to the output 
string. Octal or hexadecimal values also may be included in the string, with octal 
preceded by \ and hex by \x. Pad each value to three integers with leading zeroes. 

Example 

The following entry 
LAYER: 1 

STATE: prlnt_message 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: 

1 

prints(“End of test."); 

) 

produces the following output to a printer: 

End of lest. 
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